home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / REFERENC / TPR / TPR5.TXT < prev    next >
Text File  |  1992-10-19  |  101KB  |  2,579 lines
  1.                                    Chapter 5
  2.                                     of the
  3.                             Turbo Pascal Reference
  4.  
  5.                           The Graph Library Reference
  6.  
  7.  
  8. This chapter is part of the Turbo Pascal Reference electronic freeware book (C)
  9. Copyright 1992 by Ed Mitchell.  This freeware book contains supplementary
  10. material to Borland Pascal Developer's Guide, published by Que Corporation,
  11. 1992.  However, Que Corporation has no affiliation with nor responsibility for
  12. the content of this free book.  Please see Chapter 1 of the Turbo Pascal
  13. Reference for important information about your right to distribute and use this
  14. material freely.  If you find this material of use, I would appreciate your
  15. purchase of one my books, such as the Borland Pascal Developer's Guide or
  16. Secrets of the Borland C++ Masters, Sams Books, 1992.  Thank you.
  17.  
  18.  
  19.      This chapter contains detailed reference information, including examples,
  20. on all procedures, functions, variables and constants that make up the Graph
  21. unit of Turbo Pascal.  Additional information on using these features is also
  22. described in Chapter 5, "Turbo Pascal Graphics" of the Borland Pascal
  23. Developer's Guide.
  24.  
  25.  
  26. Arc procedure
  27. ----------------------------------------------------------------
  28. Declaration:        
  29.      procedure Arc ( X, Y : Integer; StAngle, 
  30.                     EndAngle, Radius : Word );
  31.  
  32. Example:
  33.      { Draw an arc from 0 degs to 90 degs, center on (100, 100)
  34.      and having a radius of 80 pixels }
  35.      Arc ( 100, 100, 0, 90, 80 );
  36.  
  37. Purpose:
  38.      Use Arc for drawing an arc in the current color, where the arc is a subset
  39. of a circle's circumference.  X and Y specifiy the mid-point of a circle having
  40. a size specified by Radius.  StAngle marks the starting point for the arc and
  41. EndAngle marks the ending point, as shown in this drawing:
  42.  
  43. ***FIG5ARC.PCX***
  44.  
  45. As shown in the drawing, 0 degrees is on a horizontal line going directly to
  46. the right (at the 3 O'clock position of a clock), 90 degrees is straight up
  47. (noon or Midnite), 180 degrees is to the left, 270 degrees is straight down,
  48. and 360 degrees is back around to the 3 O'clock position.
  49.      If circles look more like ellipses on your display, you will need to call
  50. SetAspectRatio which adjusts the algorithm used by both the circle and arc
  51. drawing code.  See SetAspectRatio for details.
  52.  
  53.  
  54. ArcCoordsType procedure
  55. ----------------------------------------------------------------
  56. Declaration:
  57.      ArcCoordsType = record
  58.        X, Y : Integer;
  59.        XStart, YStart : Integer;
  60.        XEnd, YEnd : Integer;
  61.      end;
  62.  
  63. See GetArcCoords, SetArcCoords
  64.      
  65.  
  66. Bar procedure
  67. ----------------------------------------------------------------
  68. Declaration:
  69.      procedure Bar ( X1, Y1, X2, Y2 : Integer );
  70.  
  71. Example:
  72.      See Chapter 5, "Turbo Pascal Graphics" in the Borland Pascal Developer's
  73. Guide, for completed information on charting, and a complete generalized bar
  74. chart display programs.
  75.  
  76. Purpose:
  77.      Use Bar for drawing filled rectangular regions, especially for use in
  78. drawing bar charts.  Note that Bar does not create a bounding rectangle;
  79. instead it fills the region specified by X1,Y1 for the upper left corner and
  80. X2,Y2 at the lower right corner, using the current fill pattern and interior
  81. color selected with SetFillStyle or SetFillPattern.  If you wish to have a
  82. rectangle drawn as a border around the bar, you should call Rectangle or call
  83. Bar3D with Bar3D's Depth parameter set to zero.
  84.      Unfortunately, drawing Bar charts requires quite a bit more work than
  85. merely displaying individual bars.  For this reason, Chapter 5, "Turbo Pascal
  86. Graphics", in the Borland Pascal Developer's Guide provides a complete routine
  87. for drawing professional quality bar charts, including titles, Y axis grids, X
  88. axis labels and scaling of data.
  89.  
  90.  
  91. Bar3D procedure
  92. ----------------------------------------------------------------
  93. Declaration:
  94.      procedure Bar3D ( X1, Y1, X2, Y2 : Integer; 
  95.                     Depth : Word; Top : Boolean );
  96.  
  97. Example:
  98.      { Draw a 3D bar whose upper left corner is at (StartX,
  99.      StartY), having a width of Width and a height of Height.
  100.      The "depth" effect is set to 40 pixels and a "top" placed on
  101.      the bar }
  102.      Bar3D ( StartX, StartY, StartX + Width, StartY + Height, 
  103.           40, TopOn );
  104.  
  105. Purpose:
  106.      Bar3D is the pseudo 3-dimensional equivalent of Bar, in that Bar3D draws
  107. and fills a rectangular region suited for use in a bar graph, but adds an
  108. optional simulated depth to the bar.  Depth controls the number of pixels of
  109. simulated depth.
  110.      Because Depth is in pixels, you should calculate the relative depth from
  111. the width specified by the X1 and X2 coordinates.  For example, to set the
  112. Depth to 30% of the width, write:
  113.      (X2 - X1 + 1) * 0.30
  114. where 0.30 represents 30%.  If you wish to avoid real number arithmetic, you
  115. can use an integer divisor instead, such as div 2, div 4 or div 8, as shown:
  116.  
  117.      Bar3D( X1, Y1, X2, Y2, (X2 - X1 + 1) div 8, TopOn );
  118.  
  119. By setting Depth to zero, Bar3D draws a 2-dimensional bar just like Bar, but
  120. Bar3D  adds the bounding rectangle that Bar does not include.
  121.      TopOn and TopOff are Graph unit constants set to True and False,
  122. respectively.  When the Top parameter is set to True, a simulated 3-D cap is
  123. placed on the column; when False, no cap is placed on the column.
  124.      The interior of the 3-dimensional column is drawn using the pattern and
  125. color set by SetFillStyle or SetFillPattern.  The bounding rectangle is drawn
  126. with the line style set with SetLineStyle and color selected by SetColor.
  127.      When you use Bar3D, be aware that the depth portion of the column is not a
  128. solid object - if you draw a 3D bar on top of an existing drawing, especially a
  129. background grid, the background will show through the simulated depth section.
  130.  
  131.  
  132. Circle
  133. ----------------------------------------------------------------
  134. Declaration:
  135.      procedure Circle ( X, Y : Integer; Radius : Word );
  136.  
  137. Example:
  138.      To draw a circle centered on the mid-point of the display, and having a
  139. radius of 50 pixels, write:
  140.      Circle ( GetMaxX div 2, GetMaxY div 2,  50 );
  141. To change the color of the Circle, call SetColor before calling Circle.
  142.  
  143. Purpose:
  144. ***FIG5CIR.PCX***
  145.      Draws a circle haviing a radius of Radius pixels, centered about (X,Y),
  146. using the current color selected with a previous SetColor procedure call.  If
  147. your circles look more like ellipses than circles, refer to SetAspectRatio for
  148. information on making an adjustment to the circle drawing algorithm that can
  149. fix this problem.
  150.      If you wish to draw a filled or "solid" circle, use the PieSlice
  151. procedure, setting the starting angle to 0 and the ending angle to 360.  Or use
  152. the FillEllipse procedure setting the XRadius and YRadius parameters to the
  153. same radius value.  For example,
  154.      FillEllipse ( GetMaxX div 2, GetMaxY div 2, 50, 50 );
  155. See Arc, Ellipse, FillEllipse, GetAspectRatio, PieSlice, SetAspectRatio
  156.  
  157.  
  158. ClearDevice
  159. ----------------------------------------------------------------
  160. Declaration:
  161.      procedure ClearDevice;
  162.  
  163. Example:
  164.      ClearDevice;
  165.  
  166. Purpose:
  167.      Use ClearDevice to erase or clear the current graphical screen, resetting
  168. the screen to the current background color (see SetBkColor) and moving the
  169. current pointer (CP) to (0,0).
  170. See ClearViewPort, SetBkcolor
  171.  
  172.  
  173. ClearViewPort
  174. ----------------------------------------------------------------
  175. Declaration:
  176.      procedure ClearViewPort;
  177.  
  178. Example:
  179.      To clear out the area bounded by (100, 100) at the upper left corner, and
  180. (400, 300) at the lower right corner, write:
  181.  
  182.      SetViewPort ( 100, 100, 400, 300, ClipOn );
  183.      ClearViewPort;
  184.  
  185. Purpose:
  186. Use ClearViewPort to erase or clear the graphical screen area within the
  187. currently defined viewport, resetting the current pointer (CP) to (0,0)
  188. (relative to the viewport).  By setting a view port smaller than the screen,
  189. you can use ClearViewPort to selectively clear just a portion of the screen.
  190. See ClearDevice, SetViewPort
  191.  
  192.  
  193. CloseGraph
  194. ----------------------------------------------------------------
  195. Declaration:
  196.      procedure CloseGraph;
  197.  
  198. Example:
  199.      CloseGraph;
  200.  
  201. Purpose:
  202.      When you are finished using the graphics system, call CloseGraph to shut
  203. down the graphics system and return the screen to text mode operation. 
  204. CloseGraph frees up all memory allocations used by the graphics system for
  205. drivers, fonts and temporary space.  To reuse graphics after calling
  206. CloseGraph, you must again call InitGraph.  If you only wish to temporarily
  207. switch to text mode, call RestoreCrtMode instead.  Then, to switch back to
  208. graphics, call SetGraphMode.  
  209. See InitGraph, RestoreCrtMode, SetGraphMode
  210.  
  211.  
  212. DetectGraph
  213. ----------------------------------------------------------------
  214. Declaration:
  215.      procedure DetectGraph
  216.           ( var GraphDriver, GraphMode : Integer );
  217.  
  218. Example:
  219.      DetectGraph ( GraphDriver, GraphMode );
  220.      InitGraph ( GraphDriver, GraphMode );
  221.  
  222. Purpose:
  223.      DetectGraph is called by InitGraph when InitGraph's GraphDriver parameter
  224. is set to Detect.  DetectGraph examines the graphics hardware; if none is
  225. found, both GraphDriver and the GraphResult function return grNotDetected (-2).
  226. Otherwise, DetectGraph sets GraphDriver to one of the graphics driver constants
  227. and selects an appropriate GraphMode (See InitGraph for details).
  228.      DetectGraph can not distinguish between an IBM 8514 interface and the VGA
  229. interface which is a subset of the 8514's capabilities.  Hence, for the 8514,
  230. DetectGraph will return the VGA driver constant.  If you wish to use the 8514's
  231. capabilities, you must explicitly set GraphDriver to IBM8514 prior to calling
  232. InitGraph.
  233.      Normally, your programs have no need to call DetectGraph.  However, if for
  234. some reason you wish to override the default selection that InitGraph makes
  235. when autodetecting the hardware, you may wish to call DetectGraph prior to
  236. calling InitGraph, check the result, make changes to GraphDriver and GraphMode,
  237. as needed, and then call InitGraph with explicit selection of the driver and
  238. mode.
  239. See GraphResult, InitGraph
  240.  
  241.  
  242. DrawPoly
  243. ----------------------------------------------------------------
  244. Declaration:
  245.      procedure DrawPoly ( NumPoints : Word; var PolyPoints );
  246.  
  247. Example:
  248. const
  249.      { Describe a "house" shape using an array of 6 points }
  250.      House       : Array[1..6] of PointType =
  251.      ((X:100; Y:100), (X:60;Y:140), (X:60; Y:180), (X:140;Y:180),
  252.      (X:140; Y:140), (X:100; Y:100) );
  253.      ...
  254.      { Draw the house on the screen }
  255.      DrawPoly ( 6, House );
  256.  
  257. Purpose:
  258.      Use DrawPoly for drawing simple or complex polygon shapes, where each
  259. vertice is specified with an (X, Y) coordinate (parameter PolyPoints) and the
  260. total number of vertices is indicated with NumPoints.  The polygon is drawn in
  261. a "connect the dots" fashion, moving from vertice 1 to vertice 2 to vertice 3
  262. and so on.  
  263. ***FIG5HOU.PCX***
  264.      If the polygon encloses a region, then you must specify one of the points
  265. at least twice.  In the illustration above, drawing the triangle requires
  266. PolyPoints to list vertices 1, 2, 3, and then draw the final segment from
  267. vertice 3 back to 1.  As a result, PolyPoints must contain 4 sets of
  268. coordinates (1, 2, 3, and 1).
  269.      The polygon is drawn using the current SetColor color, and may be XOR'd on
  270. to the screen (for easy erasure) using SetWriteMode (XORPut) (See
  271. SetWriteMode).  If you wish to draw a filled polygon, use FillPoly instead of
  272. DrawPoly.
  273. See FillPoly, GraphResult, SetColor, SetLineStyle and SetWriteMode
  274.      
  275.  
  276. Ellipse
  277. ----------------------------------------------------------------
  278. Declaration:
  279.      procedure Ellipse ( X, Y:Integer; StAngle, EndAngle : Word; 
  280.                     XRadius, YRadius : Word );
  281.  
  282. Example:
  283.      { Draw a full ellipse centered at X, Y, having X radius of
  284.      150 and Y radius of 75 }
  285.      Ellipse ( X, Y, 0, 360, 150, 75 );
  286.  
  287. Purpose:
  288.      Using the current color selected with SetColor, draws an ellipse or
  289. portion of an ellipse (an elliptical arc) with a center at (X, Y), and having X
  290. axis and Y axis radii specified by XRadius and YRadius, respectively.  To draw
  291. a vertical ellipse, set YRadius to a larger value than XRadius; to draw a
  292. horizontal ellipse, set XRadius to a larger value than YRadius.
  293.      If you set StAngle to 0 and EndAngle to 360, a full ellipse is drawn.  To
  294. draw only a subset of the ellipse, set StAngle and EndAngle as required.  The
  295. angular measurement for all arc and circular drawing procedures is made from 0
  296. degrees at the 3 O'clock position, and rotating counter-clockwise around to 360
  297. degrees.
  298. ***FIG5ELL.PCX***
  299.      To draw a filled in ellipse, use FillEllipse.
  300. See Arc, Circle, FillEllipse, SetAspectRatio, SetColor
  301.  
  302.  
  303. FillEllipse
  304. ----------------------------------------------------------------
  305. Declaration:        
  306.      procedure FillEllipse
  307.           (X, Y: Integer; XRadius, YRadius : Word);
  308.  
  309. Example:
  310.      SetColor(4);                       { Set border color }
  311.      SetFillStyle ( HatchFill, 3 );     { Set interior style and
  312.                                         color }
  313. FillEllipse ( 100, 100, 50, 70 );       {Draw a vertical ellipse}
  314.  
  315. Purpose:
  316.      Draws an ellipse, like the Ellipse procedure, using the current SetColor
  317. selection for the ellipse outline, but fills the interior with the color and
  318. pattern set by SetFillStyle or SetFillPattern.  XRadius specifies the X axis
  319. radius and YRadius specifies the Y axis radius.
  320. See Arc, Circle, Ellipse, SetAspectRatio
  321.  
  322.  
  323. FillPoly procedure
  324. ----------------------------------------------------------------
  325. Declaration:
  326.      procedure FillPoly ( NumPoints : Word; var PolyPoints);
  327.  
  328. Example:
  329.  
  330. const
  331.      { Describe a "house" shape using an array of 6 points }
  332.      House       : Array[1..6] of PointType =
  333.      ((X:100; Y:100), (X:60;Y:140), (X:60; Y:180), (X:140;Y:180),
  334.      (X:140; Y:140), (X:100; Y:100) );
  335.      ...
  336.      { Select a fill pattern for the house }
  337.      SetFillStyle ( HatchFill, 4 );
  338.      { Draw the house on the screen }
  339.      FillPoly ( 6, House );
  340.  
  341. Purpose:
  342.      Use FillPoly for drawing and filling polygon shapes, where each vertice is
  343. specified with an (X, Y) coordinate (parameter PolyPoints) and the total number
  344. of vertices is indicated with NumPoints.  The polygon is drawn in a "connect
  345. the dots" fashion, moving from vertice 1 to vertice 2 to vertice 3 and so on. 
  346. See DrawPoly for sample illustration.
  347.      For a filled polygon, you must specify a sequence of points that result in
  348. an enclosed area.  
  349.      The polygon outline is drawn in the current line style (see SetLineStyle)
  350. using the current color (see SetColor) and filled with the current pattern and
  351. pattern color set by SetFillStyle or SetFillPattern.  The SetColor color used
  352. for the outline, and the color used for the interior drawing need not be the
  353. same.  The SetWriteMode setting should not be used for solid objects as it does
  354. not affect the interior of the object.
  355. See DrawPoly, SetColor, SetFillPatttern, SetFillStyle, SetLineStyle
  356.  
  357.  
  358. FillSettingsType type
  359. ----------------------------------------------------------------
  360. Declaration:
  361.      FillSettingsType = record
  362.        Pattern : Word;
  363.        Color : Word;
  364.      end;
  365.  
  366. See GetFillSettings, GetFillPattern, SetFillPattern, SetFillStyle
  367.  
  368.  
  369. FillPatternType type
  370. ----------------------------------------------------------------
  371. Declaration:        
  372.      FillPatternType = array[1..8] of Byte;
  373.     
  374. See GetFillSettings, GetFillPattern, SetFillPattern, SetFillStyle
  375.  
  376.  
  377. FloodFill
  378. ----------------------------------------------------------------
  379. Declaration:        
  380.     procedure FloodFill (X, Y: Integer; Border : Word );
  381.  
  382. Example:
  383.     SetColor (4);                  { Set border color }
  384.     Rectangle ( 100, 100, 200, 200 );{ Draw rectangle in that
  385.                                    color }
  386.     SetFillStyle ( HatchFill, 5 ); { Prepare to hatch fill the
  387.                                    rectangle }
  388.     FloodFill ( 110, 110, 4); { Fill the interior to matching
  389.                                    color 4 }
  390.  
  391. Purpose:
  392.     Use FloodFill to fill the interior of an object that is bound by a border
  393. having the color specified in the Border parameter.  To fill the interior, you
  394. must insure that (X, Y) describes a point inside the object to be filled, and
  395. that the object is bounded.  If (X, Y) lies outside the object, then everything
  396. outside the given color boundary is filled.  If there is a "hole" in the
  397. boundary area, then the color will "leak out" and potentially cover the entire
  398. screen.  If (X, Y) is outside the boundaries of the object, FloodFill will fill
  399. the screen area on the outside if the object.
  400.     If a problem occurs during FloodFill execution, GraphResult is set to
  401. grNoFloodMem (-7).
  402. See  Circle, DrawPoly, GraphResult, Rectangle, SetColor, SetFillStyle,
  403. SetFillPattern
  404.  
  405.  
  406. GetArcCoords
  407. ----------------------------------------------------------------
  408. Declaration:
  409.     procedure GetArcCoords (var ArcCoords : ArcCoordsType );
  410.  
  411. Purpose:
  412.     Returns a record structure (see ArcCoordsType) containing the X and Y
  413. coordinates of the mid-point of the defining ellipse, the starting and ending
  414. angles, and the internally calculated ending position of the arc, as XEnd and
  415. YEnd.
  416. See Arc, Circle, Ellipse, FillEllipse, PieSlice
  417.  
  418.  
  419. GetAspectRatio
  420. ----------------------------------------------------------------
  421. Declaration:        
  422.     procedure GetAspectRatio (var Xasp, Yasp : Word );
  423.  
  424. Purpose:
  425.     Returns Xasp and Yasp, which when dividing Xasp / Yasp produces the aspect
  426. ratio of the monitor.  These values are used by SetAspectRatio to adjust the
  427. computation used in drawing arcs, circles, ellipses and alll other objects that
  428. are circular in nature.
  429. See SetAspectRatio
  430.  
  431.  
  432. GetBkColor function
  433. ----------------------------------------------------------------
  434. Declaration:
  435.     function GetBkColor : Word;
  436.  
  437. Purpose:
  438.     Use GetBkColor to determine the index of the current palette color entry
  439. being used as the background color.  GetBkColor returns a value from 0 up to
  440. 15, depending on which graphics driver and mode are in use.
  441.  
  442.  
  443. GetColor function
  444. ----------------------------------------------------------------
  445. Declaration:        function GetColor : Word;
  446.  
  447. Purpose:
  448.     Use GetColor to obtain the setting of the current drawing color that was
  449. last set by calling SetColor.  GetColor returns a value in the range of 0 up to
  450. 15.
  451.  
  452.  
  453. GetDefaultPalette function
  454. ----------------------------------------------------------------
  455. Declaration:
  456.     function GetDefaultPalette (var Palette : PaletteType);
  457.  
  458. Purpose:
  459.     Use GetDefaultPalette to retrieve the default color palette for the current
  460. graphics driver.  You can use GetDefaultPalette, after calling InitGraph, to
  461. save a copy of the default palette in to a local variable.  During program
  462. execution, if you have a need to restore the graphics palette to its original
  463. setting, you can do so by passing the saved palette variable to SetAllPalette.
  464. See PaletteType, SetAllPalette, SetPalette
  465.  
  466.  
  467. GetDriverName function
  468. ----------------------------------------------------------------
  469. Declaration:
  470.     function GetDriverName : String;
  471. Example:
  472.     OutTextXY( 1, 40, 'The current graphics driver is ' +
  473.                     GetDriverName );
  474.  
  475. Purpose:
  476.     Use GetDriverName to obtain the name of the current graphics driver (for
  477. example, EGAVGA).
  478. See InitGraph.
  479.  
  480.  
  481. GetFillPattern procedure
  482. ----------------------------------------------------------------
  483. Declaration:
  484.     procedure GetFillPattern(var FillPattern: FillPatternType);
  485.  
  486. Purpose:
  487.     Use GetFillPattern to retrieve the current setting of the user defined fill
  488. pattern that was last set with SetFillPattern (See SetFillPattern).  The data
  489. is returned in an array of bytes (see FillPatternType).  If there has not yet
  490. been a user defined pattern assigned with SetFillPattern, then every value in
  491. the array is set to $FF (decimal 255).
  492. See FillPatternType, SetFillStyle, SetFillPattern
  493.  
  494.  
  495. GetFillSettings procedure
  496. ----------------------------------------------------------------
  497. Declaration:
  498.     procedure GetFillSettings (var FillInfo: FillSettingsType);
  499.  
  500. Purpose:
  501.     Use GetFillSettings to retrieve the current setting of the pattern used to
  502. fill the interior of enclosed objects.  FillSettingsType (see FillSettingsType)
  503. contains two fields, Pattern and Color, both Word data types.  Pattern returns
  504. a value corresponding to one of the constants used in selecting a fill style
  505. (see SetFillStyle), or is set to the constant value UserFill, meaning that a
  506. user defined pattern is currently active.  The user defined pattern is then
  507. retrieved by calling GetFillPattern.
  508.  
  509.  
  510. GetGraphMode function
  511. ----------------------------------------------------------------
  512. Declaration:
  513.     function GetGraphMode : Integer;
  514.  
  515. Example:
  516.     GraphDriver := Detect;
  517.     InitGraph ( GraphDriver, GraphMode, '\TP\BGI');
  518.     ...
  519.     RestoreCrtMode;                { Return to text mode }
  520.     ...
  521.     SetGraphMode ( GetGraphMode ); { Return to graphics mode }
  522.     ...
  523.     
  524. Purpose:
  525.     Use GetGraphMode to determine the current graphics mode set by InitGraph or
  526. SetGraphMode.  For example, a VGA adaptor can provide 3 modes of operation:
  527. 640x200, 640x350 and 640x480.  GetGraphMode returns a value from 0 to 5
  528. indicating which of the modes is currently active, where the value depends on
  529. the graphics driver in use.  As indicated in the example above, the most common
  530. use of GetGraphMode is to obtain the current mode value for passing to
  531. SetGraphMode when switching back and forth between text and graphics modes.
  532.  
  533. The following table shows the various values:
  534.  
  535. Return Value         Driver        Mode Constant  Resolution                   
  536. Palette     Pages
  537.     0        CGA     CGAC0       320x200      C0   1
  538.     1                CGAC1       320x200      C1   1
  539.     2                CGAC2       320x200      C2   1
  540.     3                CGAC3       320x200      C3   1
  541.     4                CGAHi       640x200      B&W  1
  542.  
  543.     0        MCGA    MCGAC0      320x200      C0   1
  544.     1                MCGAC1      320x200      C1   1
  545.     2                MCGAC2      320x200      C2   1
  546.     3                MCGAC3      320x200      C3   1
  547.     4                MCGAMed     640x200      2 color        1
  548.     5                MCGAHi      640x480      2 color        1
  549.  
  550.     0        EGA     EGALo       640x200      16 color       4
  551.     1                EGAHi       640x350      16 color       2
  552.  
  553.     0        EGA64   EGA64Lo     640x200      16 color       1
  554.     1                EGA64Hi     640x350      4 color        1
  555.  
  556.     3        EGAMono EGAMonoHi   640x350 [64k card]          2 color           
  557. 1
  558.     3                EGAMonoHi   640x350 [256k card]         2 color           
  559. 2
  560.  
  561.     0        HercMono            HercMonoHi   720x348        2 color           
  562. 2
  563.     
  564.     0        ATT400  ATT400C0    320x200      C0   1
  565.     1                ATT400C1    320x200      C1   1
  566.     2                ATT400C2    320x200      C2   1
  567.     3                ATT400C3    320x200      C3   1
  568.     4                ATT400Med   640x200      2 color        1
  569.     5                ATT400Hi    640x400      2 color        1
  570.  
  571.     0        VGA     VGALo       640x200      16 color       2
  572.     1                VGAMed      640x350      16 color       2
  573.     2                VGAHi       640x480      16 color       1
  574.  
  575.     0        PC3270  PC3270Hi    720x350      2 color        1
  576.  
  577.     0        IBM8514 IBM8514Lo   640x480      256 color      1
  578.     1                IBM8514Hi   1024x768     256 color      1
  579.  
  580. See GetDriverName, GetModeName, InitGraph, RestoreCrtMode, SetGraphMode,
  581. SetVisualPage
  582.  
  583.  
  584. GetImage procedure
  585. ----------------------------------------------------------------
  586. Declaration: 
  587.      procedure GetImage( X1, Y1, X2, Y2 : Integer; var BitMap );
  588.  
  589. Example:
  590.      See PutImage.      
  591. Purpose:
  592.      Use GetImage to copy an area of the graphics screen into a separate memory
  593. buffer.  The area to copy is bounded by (X1, Y1)  and (X2, Y2), and is copied
  594. to the buffer specified by the BitMap parameter.  BitMap must define a buffer
  595. equal to the memory required to store the image, plus 6 additional bytes.  The
  596. easiest way to determine the correct size is to call the ImageSize function,
  597. which automatically computes the amount of memory required, including the 6
  598. additional bytes.
  599. See ImageSize, OutImage
  600.  
  601.  
  602. GetLineSettings
  603. ----------------------------------------------------------------
  604. Declaration: 
  605.      procedure GetLineSettings
  606.        (var LineInfo : LineSettingsType );
  607.  
  608. Purpose:
  609.      Use this to determine the current line draw settings that were set by
  610. calling SetLineStyle.  GetLineSettings returns a record containing information
  611. about the current line sytle, pattern and thickness. 
  612. See LineSettingsType, SetLineStyle
  613.  
  614.  
  615. GetMaxColor function
  616. ----------------------------------------------------------------
  617. Declaration: 
  618.      function GetMaxColor : Word;
  619.  
  620. Purpose:
  621.      Use GetMaxColor to determine the highest color value to be passed as a
  622. parameter to SetColor.  Color selections range from 0 up to 15 for the VGA and
  623. some EGA cards, although several modes support only 2 colors having values of 0
  624. and 1.  Four color  modes have values of 0, 1, 2 and 3.
  625. See SetColor
  626.  
  627.  
  628. GetMaxMode function
  629. ----------------------------------------------------------------
  630. Declaration: 
  631.      function GetMaxMode : Word;
  632.  
  633. Purpose:
  634.      Mode values vary from 0 up to a maximum of 5, depending on the graphics
  635. driver in use (See GetGraphMode for a table of all possible mode values). 
  636. GetMaxMode returns the highest mode value available for the current graphics
  637. driver.
  638. See GetGraphMode, GetModeRange, InitGraph
  639.  
  640. GetMaxX function
  641. ----------------------------------------------------------------
  642. Declaration: 
  643.      function GetMaxX : Integer;
  644.  
  645. Purpose:
  646.      GetMaxX returns the maximum resolution of pixels in the X axis direction. 
  647. The return value is zero-relative meaning that a 640x480 VGA display has a
  648. GetMaxX return value of 639.
  649.  
  650.  
  651. GetMaxY function
  652. ----------------------------------------------------------------
  653. Declaration: 
  654.      function GetMaxY : Integer;
  655.  
  656. Purpose:
  657.      GetMaxY returns the maximum resolution of pixels in the Y axis direction. 
  658. For example, on a 640x480 VGA display, GetMaxY returns a zero-relative value of
  659. 479.
  660.  
  661.  
  662. GetModeName function
  663. ----------------------------------------------------------------
  664. Declaration: 
  665.      function GetModeName ( ModeNumber : Integer);
  666.  
  667. Example:
  668.      InitGraph( GraphDriver, GraphMode, '\TP\BGI');
  669.      ...
  670.      {After switching to graphics screen, show available modes}
  671.      for I := 0 to GetMaxMode do
  672.      begin
  673.        ModeName := GetModeName( I );
  674.        OutTextXY( 5, (I+1)*TextHeight( ModeName ), ModeName );
  675.      end;
  676.  
  677. On my configuration this displays:
  678.  
  679.      640x200 EGA
  680.      640x350 EGA
  681.      640x480 VGA
  682.  
  683. Purpose:
  684.      Use GetModeName to return a string containing the graphics mode name
  685. corresponding to ModeNumber.  This function can be used to build a menu of
  686. choices, listing each of the available modes for the current graphics driver.
  687. See GetGraphMode, InitGraph
  688.  
  689. GetModeRange procedure
  690. ----------------------------------------------------------------
  691. Declaration:
  692.      procedure GetModeRange( GraphDriver : Integer;
  693.                         var LoMode, HiMode : Integer );
  694.  
  695. Example:
  696.  
  697.      GetModeRange ( CurrentDriver, MinMode, MaxMode );
  698.  
  699. Purpose:
  700.      Use GetModeRange to determine the valid mode values for a particular
  701. driver.  Pass one of the driver constants (CGA, MCGA, EGA, EGA64, HERC, VGA,
  702. etc) to GraphDriver.  On return, LoMode and HiMode are set to the range of
  703. permissible mode values (See also GetGraphMode), or are set to -1 if
  704. GraphDriver specifies an invalid driver.  To obtain the mode values for the
  705. current driver, use the constant CurrentDriver as the driver selection.
  706.  
  707.  
  708. GetPalette procedure
  709. ----------------------------------------------------------------
  710. Declaration: 
  711.      procedure GetPalette ( var Palette : PaletteType );
  712.  
  713.  
  714. Purpose:
  715.      Use GetPalette to copy the current palette to parameter variable Palette
  716. (see PaletteType).  Palette returns a record structure containing Colors, an of
  717. array of 0 to 15 palette values, and a Size field indicating how many of the
  718. array entries are in use:  Colors[0]..Colors[Size-1].
  719.      You can use GetPalette to fetch the entire palette, make several changes,
  720. and then make a group of changes all at once by calling SetAllPalette.
  721.      This function should not be used in 256-color VGA mode or with the IBM
  722. 8514 driver.
  723. See GetDefualtPalette, GetPaletteSize, SetAllPalette, SetPalette
  724.  
  725.  
  726. GetPaletteSize function
  727. ----------------------------------------------------------------
  728. Declaration: 
  729.      function GetPAletteSize : Integer;
  730.  
  731. Purpose:
  732.      GetPaletteSize returns the size of the palette color table, which is the
  733. same value returned in the size field when calling GetPalette.
  734. See GetPalette, SetPalette
  735.  
  736. GetPixel function
  737. ----------------------------------------------------------------
  738. Declaration: 
  739.      function GetPixel ( X, Y : Integer );
  740.  
  741. Purpose:
  742.      Use with PutPixel to read and write individual pixel values on the
  743. display.  GetPixel returns the color of the pixel located at (X, Y).
  744. See PutPixel
  745.  
  746.  
  747. GetTextSettings procedure
  748. ----------------------------------------------------------------
  749. Declaration: 
  750.      procedure GetTextSettings (var TextInfo: TextSettingsType);
  751.  
  752. Purpose:
  753.      Use GetTextSettings to retrieve a record containing all the current
  754. settings (font, direction, size and justfication) that have been set by calling
  755. SetTextStyle and SetTextJustify.
  756. See TextSettingsType, SetTextJustify, SetTextStyle
  757.  
  758.  
  759. GetViewSettings procedure
  760. ----------------------------------------------------------------
  761. Declaration: 
  762.      procedure GetViewSettings(var ViewPort : ViewPortType );
  763.  
  764. Purpose:
  765.      GetViewSettings returns the coordinates of the current view port and the
  766. status of the Clip clipping flag.  The information is returned in a
  767. ViewPortType record structure, containing X1, Y1, X2, Y2 and Clip fields.
  768. See SetViewPort, ViewPortType
  769.  
  770.  
  771. GetX function
  772. ----------------------------------------------------------------
  773. Declaration: 
  774.      function GetX : Integer;
  775.  
  776. Purpose:
  777.      Use GetX to obtain the X coordinate of the current pointer, where the
  778. returned value is relative to the current viewport setting.  Note that if you
  779. change the viewport, the current pointer is reset to (0, 0) relative to the new
  780. viewport and GetX will then return 0.
  781. See GetViewsettings, GetY, SetViewPort
  782.  
  783.  
  784. GetY function
  785. ----------------------------------------------------------------
  786. Declaration: 
  787.      function GetY : Integer;
  788.  
  789. Purpose:
  790.      Use GetY to obtain the Y coordinate of the current pointer, where the
  791. returned value is relative to the current viewport setting.  Changing the
  792. viewport causes the current pointer to be reset to (0, 0) relative to the new
  793. viewport setting, and hence, GetY will return 0.
  794.  
  795.  
  796. Graph constants (all except grXXXX constants)
  797. ----------------------------------------------------------------
  798. The graph unit contains a large number of constant identifiers that are used to
  799. pass and return values between graph unit procedures and functions.  Except for
  800. the grXXXX result code constants, none of the constant identifiers adhere to
  801. any particular naming scheme.  As a result, the entire group of constants are
  802. presented in this section for easier reference.
  803.  
  804.  
  805.  
  806. Constant       Purpose
  807. -------------  ------------------------------------------
  808. (Driver and Mode Selection Constants)
  809.  
  810. CurrentDriver  Passed to GetModeRange to select the current
  811.                driver.
  812.  
  813. Detect         Used to request automatic driver selection in
  814.                InitGraph
  815.  
  816. CGA            The following constants are used or returned by
  817. MCGA           Init Graph, DetectGraph and so on.   Each
  818. EGA            constant corresponds to one of the graphics 
  819. EGA64          modes.
  820. EGAMono
  821. IBM8514
  822. HercMono
  823. ATT400
  824. VGA
  825. PC3270
  826.  
  827. Constant       Purpose
  828. -------------  ------------------------------------------
  829. (The following correspond to the respective graphics modes available for each
  830. driver.  Also see GetGraphMode.)
  831.  
  832. CGAC0          
  833.                320x200 palette 0: LightGreen, LightRed, Yellow; 1 page 
  834. CGAC1          
  835.                320x200 palette 1: LightCyan, LightMagenta, White; 1 page
  836. CGAC2          
  837.                320x200 palette 2: Green, Red, Brown; 1 page
  838. CGAC3          
  839.                320x200 palette 3: Cyan, Magenta, LightGray; 1 page
  840. CGAHi          
  841.                640x200 1 page 
  842. MCGAC0         
  843.                320x200 palette 0: LightGreen, LightRed, Yellow; 1 page
  844. MCGAC1         
  845.                320x200 palette 1: LightCyan, LightMagenta, White; 1 page
  846. MCGAC2         
  847.                320x200 palette 2: Green, Red, Brown; 1 page
  848. MCGAC3         
  849.                320x200 palette 3: Cyan, Magenta, LightGray; 1 page
  850. MCGAMed        640x200 1 page
  851. MCGAHi         640x480 1 page
  852. EGALo          640x200 16 color 4 page
  853. EGAHi          640x350 16 color 2 page
  854. EGA64Lo        640x200 16 color 1 page
  855. EGA64Hi        640x350 4 color  1 page
  856. EGAMonoHi      640x350 64K on card, 1 page; 256K on card, 2 page
  857. HercMonoHi     720x348 2 page
  858. ATT400C0       
  859.                320x200 palette 0: LightGreen, LightRed, Yellow; 1 page
  860. ATT400C1       
  861.                320x200 palette 1: LightCyan, LightMagenta, White; 1 page
  862. ATT400C2       320x200 palette 2: Green, Red, Brown; 1 page
  863. ATT400C3       
  864.                320x200 palette 3: Cyan, Magenta, LightGray; 1 page
  865. ATT400Med      640x200 1 page
  866. ATT400Hi       640x400 1 page
  867. VGALo          640x200 16 color 4 page
  868. VGAMed         640x350 16 color 2 page
  869. VGAHi          640x480 16 color 1 page
  870. PC3270Hi       720x350 1 page
  871. IBM8514Lo      640x480 256 colors
  872. IBM8514Hi      1024x768 256 colors
  873.  
  874. Constant       Purpose
  875. -------------  ------------------------------------------
  876. (Color selection related constants.)
  877.  
  878. MaxColors      Maximum number of colors, zero relative.
  879. Black          This set of constants is used for setting colors
  880.                in the color palette using SetPalette and
  881. Blue           SetAllPalette
  882. Green
  883. Cyan
  884. Red
  885. Magenta
  886. Brown
  887. LightGray
  888. DarkGray
  889. LightBlue
  890. LightGreen
  891. LightCyan
  892. LightRed
  893. LightMagenta
  894. Yellow
  895. White
  896.  
  897. EGABlack       Selects EGA equivalent colors on the IBM 8514 display.
  898. EGABlue        See SetRGBPalette.
  899. EGAGreen
  900. EGACyan
  901. EGARed
  902. EGAMagenta
  903. EGABrown
  904. EGALightgray
  905. EGADarkgray
  906. EGALightblue
  907. EGALightgreen
  908. EGALightcyan
  909. EGALightred
  910. EGALightmagenta
  911. EGAYellow
  912. EGAWhite
  913.  
  914. Constant       Purpose
  915. -------------  ------------------------------------------
  916. (Drawing parameter constants)
  917.  
  918. ClipOn  = true;   Parameter to SetViewPort.
  919. ClipOff = false;
  920.  
  921. TopOn  = true; Parameter to Bar3D.
  922. TopOff = false;
  923.                
  924. EmptyFill      The following are used with SetFillStyle.
  925. SolidFill      See SetFillStyle for details.
  926. LineFill
  927. LtSlashFill
  928. SlashFill
  929. BkSlashFill
  930. LtBkSlashFill
  931. HatchFill
  932. XHatchFill
  933. InterleaveFill
  934. WideDotFill
  935. CloseDotFill
  936. UserFill       Selects the user defined pattern (see SetFillPattern).
  937.  
  938. NormalPut      Used with PutImage (NormalPut is equivalent to CopyPut)
  939. CopyPut
  940. XORPut
  941. OrPut
  942. AndPut
  943. NotPut
  944.  
  945. SolidLn        Selects a line style in SetLineStyle.
  946. DottedLn       Also see GetLineStyle
  947. CenterLn
  948. DashedLn
  949. UserBitLn
  950. NormWidth
  951. ThickWidth
  952.  
  953. Constant       Purpose
  954. -------------  ------------------------------------------
  955. (Text output related constants)
  956.  
  957. DefaultFont    Used in with SetTextStyle to choose the 8x8 bitmap font.
  958. TriplexFont
  959. SmallFont
  960. SansSerifFont
  961. GothicFont
  962.  
  963. HorizDir       Selects horizontal text direction with
  964.                SetTextStyle.
  965. VertDir        Selects vertical text direction.
  966.  
  967. LeftText       In SetTextJustify, selects horizontal positioning
  968.                of text around (X, Y).  See TextJustify.
  969. CenterText     
  970. RightText
  971. BottomText     Selects vertical positioning of text.
  972. TopText
  973.  
  974.  
  975.  
  976. grXXXX constants
  977. ----------------------------------------------------------------
  978. The grXXXX constants indicate error status after performing various graphics
  979. operations.  To obtain the current error status, call the GraphResult function,
  980. copying the result to a temporary value (GraphResult resets the error code to
  981. zero after each call).  You can convert the error code values shown below to
  982. textual error messages by passing the error code to GraphErrorMsg.
  983.  
  984. Constant       Value  Purpose
  985.  
  986. grOk             0    No error occurred; everything is fine.
  987. grNoInitGraph   -1    InitGraph has not yet initialized the
  988.                       graphics system
  989. grNotDetected   -2    No graphics hardware appears to be
  990.                       available on this PC.
  991. grFileNotFound  -3    The appropriate .BGI device driver file
  992.                       can not be located.
  993. grInvalidDriver -4    The .BGI device driver file is invalid;
  994.                       corrupted.
  995. grNoLoadMem     -5    There is insufficient available memory to
  996.                       load the driver.
  997. grNoScanMem     -6    Insufficient memory available for the scan
  998.                       fill buffer (used for filling in solid
  999.                       objects)
  1000. grNoFloodMem    -7    Insufficient memory to complete FloodFill
  1001.                       execution.
  1002. grFontNotFound  -8    Cannot locate the .CHR font file.
  1003. grNoFontMem     -9    Insufficient memory to load the .CHR font
  1004.                       file.
  1005. grInvalidMode   -10   Attempted to select an unacceptable
  1006.                       graphics mode.
  1007. grError         -11   Generic graphics system error.
  1008. grIOerror       -12   Error occurred in performing graphics I/O.
  1009. grInvalidFont   -13   The selected font file is invalid or
  1010.                       corrupted.
  1011. grInvalidFontNum      -14         The font number is out of range.
  1012.  
  1013.  
  1014.  
  1015. GraphDefaults
  1016. ----------------------------------------------------------------
  1017. Declaration:
  1018.      procedure GraphDefaults;
  1019.  
  1020. Purpose:
  1021.      By calling GraphDefaults, the graphics system parameters are reset to
  1022. their initial values.  GraphDefaults affects the current pointer, foreground
  1023. and background color selections, line style and patterns, fill style, color and
  1024. pattern, the viewport settings and all the font and text drawing attributes.
  1025.  
  1026.  
  1027. GraphErrorMsg function
  1028. ----------------------------------------------------------------
  1029. Declaration: 
  1030.      function GraphErrorMsg ( ErrorCode : Integer ) : String;
  1031.  
  1032. Purpose:
  1033.      Converts the ErrorCode parameter into a textual message, where ErrorCode
  1034. is one of the grXXXX constant values (See grXXXX constants) returned by
  1035. GraphResult.
  1036.  
  1037.  
  1038. GraphResult function
  1039. ----------------------------------------------------------------
  1040. Declaration: 
  1041.      function GraphResult : Integer;
  1042.  
  1043. Example:
  1044.      See PutImage.
  1045.  
  1046. Purpose:
  1047.      GraphResult contains the error code result of the most recent graphics
  1048. function (See grXXXX constants for a list of the values returned).  GraphResult
  1049. always resets the last error condition when called.  In order to use
  1050. GraphResult, it is recommend that you assign the returned value to a variable,
  1051. and then use the variable in your subsequent error handling.
  1052. See grXXXX constants, GraphErrorMsg
  1053.  
  1054.  
  1055. ImageSize function
  1056. ----------------------------------------------------------------
  1057. Declaration: 
  1058.      function ImageSize ( X1, Y1, X2, Y2 : Integer );
  1059.      
  1060. Purpose:
  1061.      ImageSize computes the number of bytes of memory needed to store the
  1062. region defined by (X1, Y1) at the upper left corner and (X2, Y2) at the lower
  1063. right corner.  ImageSize is normally used to calculate the size of the memory
  1064. buffer needed to store the image prior to calling GetImage.
  1065. See GetImage
  1066.  
  1067.  
  1068. InitGraph
  1069. ----------------------------------------------------------------
  1070. Declaration: 
  1071.      procedure InitGraph 
  1072.      (var GraphDriver : Integer; var GraphMode : Integer;
  1073.       PathToDriver : String );
  1074.  
  1075. Example:
  1076.  
  1077.      GraphDriver := Detect;
  1078.      InitGraph ( GraphDriver, GraphMode, 'C:\TP\BGI' );
  1079.      ErrorCode := GraphResult;
  1080.      if ErrorCode <> grOk then
  1081.      begin
  1082.        { Initialization failed; handle error condition here }
  1083.      end;
  1084.  
  1085. Purpose:
  1086.      InitGraph must be called prior to calling most of the graphics routines
  1087. and is used to initialize the graphics system and switch the display from text
  1088. mode to graphics mode.  InitGraph can automatically detect the type of graphics
  1089. hardware on the system, or you can explicitly select the hardware to which it
  1090. should initialize.
  1091.      For automatic detection, set GraphDriver equal to the Detect constant, and
  1092. then call InitGraph, like this:
  1093.  
  1094.      GraphDriver := Detect;
  1095.      InitGraph( GraphDriver, GraphMode, '' );
  1096.  
  1097. The PathToDriver parameter specifies where the .BGI driver files are located. 
  1098. If PathToDriver is null, then InitGraph looks in the current directory.  To
  1099. look in another directory, specify the subdirectory name here.  By default
  1100. Turbo Pascal installation places the .BGI files in the \TP\BGI directory
  1101. (although you may have elected to place them in a different subdirectory).  For
  1102. example,
  1103.  
  1104.      InitGraph( GraphDriver, GraphMode, 'C:\TP\BGI');
  1105.  
  1106. On return from InitGraph, GraphDriver is set to a value corresponding to one of
  1107. the graph driver constants (CGA, EGA, VGA, etc; see Graph constants), and
  1108. GraphMode is set to the mode in use (e.g. 640x480, 320x200, etc).  If an error
  1109. occurred, the error result is returned in GraphResult (see GraphResult and
  1110. grXXXX constants).  You should always check GraphResult, particularly after
  1111. calling InitGraph.  If the initialization failed, subsequent calls to graphics
  1112. routines will cause the program to crash.
  1113.      You can manually select a driver and mode by setting both parameters to
  1114. the appropriate values prior to calling InitGraph. For example,
  1115.  
  1116.      GraphDriver := CGA;
  1117.      GraphMode := 1;
  1118.      InitGraph ( GraphDriver, GraphMode, 'C:\TP\BGI' );
  1119.  
  1120. You may also call DetectGraph first, to automatically detect the graphics
  1121. hardware in use, and then manually modify the GraphDriver and GraphMode
  1122. parameters before calling InitGraph (See DetectGraph).
  1123.      When the graphics driver is loaded, InitGraph calls an internal procedure,
  1124. GraphGetMem, to allocate a memory buffer where it can store the driver.  As an
  1125. alternative to searching the disk and loading the driver file into memory, you
  1126. can link one or more driver files directly into your program.  See "Linking
  1127. Device Drivers and Font Files" in Chapter 5, "Turbo Pascal Graphics" in the
  1128. Borland Pascal Developer's Guide, Que Books, 1992. 
  1129.  
  1130. Important note: InitGraph and the IBM 8514
  1131.      If you use the automatic hardware detection feature with the IBM 8514
  1132. display adaptor, InitGraph will always select VGA instead of IBM 8514.  This is
  1133. because VGA is a subset of the IBM 8514 capabilities and because the 8514
  1134. cannot be distinguished from the VGA.  In order to use the IBM 8514, you must
  1135. set GraphDriver to IBM8514 prior to calling InitGraph.
  1136. See CloseGraph, DetectGraph, GraphResult, grXXXX constants
  1137.  
  1138.  
  1139. InstallUserDriver function
  1140. ----------------------------------------------------------------
  1141. Declaration: 
  1142.      function InstallUserDriver 
  1143.        ( Name : String; AutoDetect : Pointer ): Integer;
  1144.  
  1145. Example:
  1146.  
  1147.      { Install Knight Software's 256 color VGA driver }
  1148.      DriverNum := InstallUserDriver ( 'BGI256', @AutoDet );
  1149.      Errcode := GraphResult;
  1150.      if Errcode < 0 then
  1151.      { Oopsie... an error occurred ... handle it here }
  1152.  
  1153. Purpose:
  1154.      InstallUserDriver adds a third-party supplied device driver to the
  1155. internal device driver table.  Its two parameters are the name of the .BGI file
  1156. and a pointer to an automatic hardware detection routine that is used by
  1157. InitGraph when the GraphDriver parameter is set to Detect.  The pointer value
  1158. may be set to nil, in which case, the users of the driver must always insure
  1159. that they select an appropriate mode for the driver before calling InitGraph.
  1160.      The example shown above shows how you can install a third party supplied
  1161. device driver.  In this case, the code installs the BGI256 VGA 256-color driver
  1162. sold by Knight Software.  Generally, the supplier of the device driver will far
  1163. provide a routine to perform automatic detection.  It is the address of this
  1164. function, shown as @AutoDet in the example code, that should be passed to the
  1165. AutoDetectPtr parameter.
  1166.      The automatic detection routine should be a function returning an integer
  1167. result of grError if the hardware is not located, or it should return a default
  1168. mode selection.
  1169. See InitGraph
  1170.  
  1171.  
  1172. InstallUserFont function
  1173. ----------------------------------------------------------------
  1174. Declaration: 
  1175.      function InstallUserFont ( FontFileName : String ) 
  1176.        : Integer;
  1177.  
  1178. Example:
  1179.  
  1180.      CourierFont := InstallUserFont ( 'COURIER' );
  1181.      ...
  1182.      SetTextStyle ( CourierFont, HorizDir, 3 );
  1183.      OutTextXY ( X, Y, 'Courier font looks like this!' );
  1184.  
  1185. Purpose:
  1186.      Adds the font file specified by FontFileName to the internal font table,
  1187. and returns the font identification number to be used when calling
  1188. SetTextStyle.  This font ID value corresponds to the standard font constants
  1189. DefaultFont, TriplexFont and so on.  If the there is no more room to add
  1190. additional fonts, the function returns 0.
  1191. See SetTextStyle
  1192.  
  1193.  
  1194. Line procedure
  1195. ----------------------------------------------------------------
  1196. Declaration: 
  1197.      procedure Line( X1, Y1, X2, Y2 : Integer );
  1198.  
  1199. Example:
  1200.  
  1201.      { Draw diagonal line across screen }
  1202.      Line ( 0, 0, GetMaxX, GetMaxY );  
  1203.  
  1204. Purpose:
  1205.      Use Line to draw a line between (X1, Y1) and (X2, Y2), using the current
  1206. color set with SetColor and the current line attributes from SetLineStyle.  To
  1207. select copy or XOR drawing of the line, call SetWriteMode prior to calling
  1208. Line.
  1209. See LineRel, LineTo, SetColor, SetLineStyle, SetWriteMode
  1210.  
  1211.  
  1212. LineRel procedure
  1213. ----------------------------------------------------------------
  1214. Declaration: procedure LineRel( Dx, Dy : Integer );
  1215.  
  1216. Example:
  1217.  
  1218.      { Demonstrates using LineRel to draw the same object in
  1219.      multiple locations.  This routine animates a triangle  moving from the
  1220. center of the screen to the lower right.
  1221.      It uses the XOR writing mode to display the triangle, then
  1222.      XORs the triangle over itself to erase it before moving to
  1223.      the next position and drawing again }
  1224.      StartX := GetMaxX div 2;      { Setting start point at
  1225.                                   screen center }
  1226.      StartY := GetMaxY div 2;
  1227.      SetWriteMode ( XORPut );      { Use XOR writing mode }
  1228.      for I := 1 to 25 do
  1229.      begin
  1230.        for J := 1 to 2 do
  1231.        begin
  1232.          MoveTo ( StartX, StartY );{ Draw a triangle }
  1233.          LineRel ( -30, 60 );
  1234.          LineRel ( 60, 0 );
  1235.          LineRel ( -30, -60 );
  1236.          Delay ( 20 );            { Pause for 20 ms (Delay is in
  1237.                                   Crt Unit) }
  1238.        end;                        { Second XOR "draw" erases
  1239.                                   the triangle }
  1240.        StartX := StartX + 5;     { Move to a new position }
  1241.        StartY := StartY + 5;      {and draw the triangle again }
  1242.      end;
  1243.  
  1244. Purpose:
  1245.      LineRel draws a line to a new point relative to the current pointer's
  1246. location.  If (X1, Y1) is the current pointer, then calling LineRel ( Dx, Dy )
  1247. is equivalent to Line (X1, Y1, X1+Dx, Y1+Dy ).
  1248. See Line, LineTo, MoveRel, MoveTo, SetColor, SetLineStyle, SetWriteMode
  1249.  
  1250.  
  1251. LineSettingsType type
  1252. ----------------------------------------------------------------
  1253. Declaration:
  1254.  
  1255.      LineSettingsType = record
  1256.        LineStyle = Word;
  1257.        Pattern = Word;
  1258.        Thickness = Word;
  1259.      end;
  1260.  
  1261. See GetLineSettings, SetLineStyle
  1262.  
  1263.  
  1264. LineTo procedure
  1265. ----------------------------------------------------------------
  1266. Declaration: 
  1267.      procedure LineTo( X, Y : Integer );
  1268.  
  1269. Example:
  1270.  
  1271.      { Draws a vertical line of 100 pixels in length }
  1272.      MoveTo ( 100, 100 );
  1273.      LineTo ( 100, 200 );
  1274.  
  1275. Purpose:
  1276.      Starting at the location of the current pointer, LineTo draws a line to
  1277. (X, Y), using the current color from SetColor and current line style from
  1278. SetLineStyle.  As with all line drawing commands, call SetWriteMode to select
  1279. copy bits or exclusive-or (XOR) bits prior to calling LineTo.
  1280. See Line, LineRel, MoveRel, MoveTo, SetColor, SetLineStyle, SetWriteMode
  1281.  
  1282.  
  1283. MoveRel procedure
  1284. ----------------------------------------------------------------
  1285. Declaration: 
  1286.      procedure MoveRel ( Dx, Dy : Integer );
  1287.  
  1288. Example:
  1289.  
  1290.      MoveTo ( 100, 100 );
  1291.      LineTo ( 100, 200 );
  1292.      MoveRel ( 50, 50 );          { Moves CP to 150, 250 }
  1293.  
  1294. Purpose:
  1295.      Adds Dx and Dy to the X and Y coordinates of the current pointer to move
  1296. the current pointer relative to its current location.
  1297. See Line, LineRel, LineTo, MoveTo, SetColor, SetLineStyle, SetWriteMode
  1298.  
  1299.  
  1300. MoveTo procedure
  1301. ----------------------------------------------------------------
  1302. Declaration: 
  1303.      procedure MoveTo ( X, Y : Integer );
  1304.  
  1305. Purpose:
  1306.      Use MoveTo to set the coordinates of the current pointer to (X, Y).  If a
  1307. view port has been set for the screen, then X and Y are relative to the
  1308. viewport - MoveTo(0,0) positions to the upper left corner of the viewport.
  1309. See Line, LineRel, LineTo, MoveRel, SetColor, SetLineStyle, SetWriteMode
  1310.  
  1311.  
  1312. OutText procedure
  1313. ----------------------------------------------------------------
  1314. Declaration: 
  1315.      procedure OutText ( TextString : String );
  1316.  
  1317. Example:
  1318.      { Position the CP to (100, 100) }
  1319.      MoveTo ( 100, 100 );
  1320.      SetTextJustify ( CenterText, CenterText );
  1321.      {Write the text at current pointer location }
  1322.      OutText ('Hello, World!');
  1323.  
  1324. Purpose:
  1325.      Draws the contents of TextString on the graphics screen at the current
  1326. pointer's location.  TextString is drawn using the font and characteristics set
  1327. by SetTextStyle and SetTextJustify (see SetTextStyle and SetTextJustify). 
  1328. Depending on the settings of SetTextJustify, the CP can mark the location of
  1329. the either the start or end of the displayed text.  When the text is written in
  1330. the horizontal direction, CP is moved accordingly; for vertical text output, CP
  1331. is unchanged.  OutText is especially useful when writing several strings, one
  1332. after the other.  
  1333.      Problems can occur if there is insufficient room on the display to fit the
  1334. contents of TextString.  Specifically, if DefaultFont is the current font in
  1335. use, and the string is too large to fit, then nothing is displayed.  If one of
  1336. the stroked fonts is in use, the string is truncated at the edge of the screen.
  1337. You can check to see if TextString fits by calling TextWidth to determine how
  1338. many pixels are needed to display the string.  TextWidth calculates the
  1339. required display area, taking into account the current font and text size.
  1340. See OutTextXY, SetTextJustify, SetTextStyle, SetUserCharSize, TextHeight,
  1341. TextWidth
  1342.  
  1343.  
  1344. OutTextXY procedure
  1345. ----------------------------------------------------------------
  1346. Declaration: 
  1347.      procedure OutTextXY
  1348.        ( X, Y : Integer; TextString ) : String;
  1349.  
  1350. Example:
  1351.  
  1352.      { Output string at center of the screen }
  1353.      OutTextXY( GetMaxX Div 2, GetMaxY div 2, 'Hello, World!' );
  1354.  
  1355. Purpose:
  1356.      Like OutText, except that TextString is written at the coordinates
  1357. specified by X and Y, using the font and characteristics set with SetTextStyle
  1358. and SetTextJustify.  See the description for OutText regarding problems that
  1359. may occur if the length of the string exceeds the space available on the
  1360. screen.  See OutText for additional information.
  1361. See OutText, SetTextJustify, SetTextStyle, SetUserCharSize, TextHeight,
  1362. TextWidth
  1363.  
  1364.  
  1365. PaletteType type
  1366. ----------------------------------------------------------------
  1367. Declaration:
  1368.  
  1369.      PaletteType = record
  1370.        Size : Byte;
  1371.        Colors : array[0..MaxColors] of ShortInt;
  1372.      end;
  1373.  
  1374. See GetPalette, SetPalette
  1375.  
  1376.  
  1377. PieSlice procedure
  1378. ----------------------------------------------------------------
  1379. Declaration: 
  1380.      procedure PieSlice 
  1381.        ( X, Y : Integer; StAngle, EndAngle, Radius : Word );
  1382.  
  1383. Example:
  1384.      See the "The Pie Chart" in Chapter 5, "Turbo Pascal Graphics" in the
  1385. Borland Pascal Developer's Guide, Que Books, 1992.  This section describes in
  1386. detail how to create a professional quality pie chart, including chart titles,
  1387. pie slice labels, and how to create exploded pie charts.
  1388.  
  1389. Purpose:
  1390.      Use PieSlice to draw the individual pie sections that make up a pie chart.
  1391. X and Y specifiy the mid-point of the pie.  The slice is drawn between StAngle
  1392. and EndAngle, where the angles are measured with 0 degrees at the 3 O'clock
  1393. position, 90 degrees at the 12 O'Clock position, and so on, in a counter
  1394. clockwise direction.   Setting StAngle to 0, and EndAngle to 90, draws a pie
  1395. slice occupying the upper right quadrant of the pie.
  1396.      The interior of the pie may be empty or filled and colored with a pattern
  1397. as specified with SetFillStyle or SetFillPattern.  SetColor sets the color of
  1398. the bounding circle and the line segments that delineate each pie slice.  Make
  1399. sure that SetWriteMode is set to CopyPut and not XORPut.  In XOR mode, peculiar
  1400. drawing effects occur to the bounding circle and slice separation lines.
  1401.      A detailed example is given earlier in this chapter in the section titled
  1402. "The Pie Chart".  Also see the description of the Arc procedure, in this
  1403. section.
  1404. See Arc, Circle, Ellipse, FillEllipse, Sector, SetFillStyle, SetFillPattern,
  1405. SetWriteMode
  1406.  
  1407.  
  1408. PointType type
  1409. ----------------------------------------------------------------
  1410. Declaration:
  1411.  
  1412.      PointType = record
  1413.        X, Y : Integer;
  1414.      end;
  1415.  
  1416.  
  1417. PutImage procedure
  1418. ----------------------------------------------------------------
  1419. Declaration: 
  1420.      procedure PutImage 
  1421.        ( X, Y : Integer; var BitMap; BitBlt : Word );
  1422.  
  1423. Example:
  1424.  
  1425.      var
  1426.        X1, Y1, X2, Y2, Dx, Dy : Integer;
  1427.        GraphBuffer : Pointer;
  1428.      ...
  1429.      TheText := 'First Graphics Program';
  1430.      SetTextJustify (LeftText, LeftText);
  1431.      SetTextStyle( TriplexFont, HorizDir, 3);
  1432.      OutTextXY (GetMaxX div 2, GetMaxY div 2, TheText);
  1433.  
  1434.      {Prepare to "grab" the graphical text item from the screen}
  1435.      Dx := TextWidth ( TheText );
  1436.      Dy := TextHeight ( TheText );
  1437.      X1 := GetMaxX div 2;
  1438.      Y1 := GetMaxY div 2 - Dy;
  1439.      X2 := X1 + Dx;
  1440.      Y2 := GetMaxY div 2 + Dy div 2;
  1441.      GetMem ( GraphBuffer, ImageSize (X1, Y1, X2, Y2 ) );
  1442.  
  1443.      { Copy the image into GraphBuffer^ }
  1444.      GetImage ( X1, Y1, X2, Y2, Graphbuffer^ );
  1445.  
  1446.      { And copy the buffer to 5 new locations on the screen }
  1447.      for I := 0 to 5 do
  1448.        PutImage(Dy + 2*I*Dy,  Dy+2*I*Dy, GraphBuffer^, CopyPut);
  1449.  
  1450. Purpose:
  1451.      PutImage copies a bit image from a buffer to some location on the screen. 
  1452. The buffer is normally created by calling GetImage to copy a region of the
  1453. graphics screen into the buffer (See GetImage).   PutImage copies the contents
  1454. of the the buffer to the graphics screen at (X, Y), where X and Y mark the
  1455. upper left corner of the graphics region.  When GetImage creates a saved
  1456. graphic image, it saves the height and width of the original region in the
  1457. buffer.  PutImage checks these values to insure that the saved image will
  1458. actually fit on the screen beginning at location (X, Y).  If the image is wider
  1459. than the available pixels to the right of X, then the image is not copied to
  1460. the display.  However, if the image is drawn near the bottom of the screen,
  1461. then the topmost portion of the image is displayed, but those portions falling
  1462. below the bottom of the screen are clipped.
  1463.      By passing one of the predefined constants (see list) to the BitBlt
  1464. pararameter, the image may be copied or merged into the existing screen image.
  1465.      AndPut  { Ands each bit in the buffer with corresponding screen bits}
  1466.      CopyPut { Copies each bit in the buffer to corresponding position on the
  1467. screen }
  1468.      NotPut  { Inverts each bit in the buffer, and then copies the inverted
  1469. bits to the
  1470.                         screen }
  1471.      OrPut              { Ors each bit in the buffer with corresponding screen
  1472. bits }
  1473.      XORPut  { Exclusive-Ors each buffer bit with the corresponding screen bit
  1474. }
  1475.  
  1476.  
  1477. PutPixel procedure
  1478. ----------------------------------------------------------------
  1479. Declaration: 
  1480.      procedure PutPixel ( X, Y : Integer; Pixel : Word );
  1481.  
  1482. Example:
  1483.  
  1484.      for X := 0 to 50 do          { A very slow way to draw a
  1485.                                   filled in rectangle! }
  1486.        for Y := 0 to 50 do
  1487.          PutPixel ( X, Y, 4 );
  1488.  
  1489. Purpose:
  1490.      Use PutPixel to set the pixel at (X, Y) to the color value passed in the
  1491. Pixel parameter.  
  1492. See GetPixel
  1493.  
  1494.  
  1495. Rectangle procedure
  1496. ----------------------------------------------------------------
  1497. Declaration: 
  1498.      procedure Rectangle (X1, Y1, X2, Y2 : Integer);
  1499.  
  1500. Example:
  1501.      { Draw border around entire screen }
  1502.      Rectangle ( 0, 0, GetMaxX, GetMaxY );         
  1503.  
  1504. Purpose:
  1505.      Use Rectangle to draw a rectangular object on the screen, with (X1, Y1) as
  1506. the upper left corner of the rectangle, and (X2, Y2) as the lower right corner.
  1507. The rectangle's border is drawn in the current color (from the last SetColor)
  1508. using the current line attributes (from the last SetLineStyle).  The rectangle
  1509. can be either by copied or XOR'd on to the screen, depending on the most recent
  1510. setting of SetWriteMode.
  1511.      The rectangle's coordinates are always drawn relative to the current
  1512. viewport setting (see SetViewPort).  To draw a filled rectangle, see Bar and
  1513. Bar3D.
  1514. See Bar, Bar3D, SetColor, SetLineStyle, SetWriteMode
  1515.  
  1516.  
  1517. RegisterBGIdriver function
  1518. ----------------------------------------------------------------
  1519. Declaration: 
  1520.      function RegisterBGIdriver (Driver : Pointer): Integer;
  1521.  
  1522. Example:
  1523.      See "Linking Driver and Font Files" section in Chapter 5, "Turbo Pascal
  1524. Graphics", of the Borland Pascal Developer's Guide.
  1525.  
  1526. Purpose:
  1527.      When driver (.BGI) files are linked into the .EXE executable program file,
  1528. you must register the driver's location with the Graph unit.  RegisterBGIdriver
  1529. takes a pointer to the entry point routine for the driver file where the entry
  1530. point name comes from the public symbol name name that you assigned when
  1531. converting the .BGI file to a .OBJ file using BINOBJ.
  1532.      RegisterBGIdriver returns a negative value to indicate that an error has
  1533. occurred, and a positive or zero value indicates success the internal driver
  1534. number and indicates successful registration.
  1535. See "Linking Driver and Font Files", InitGraph, RegisterBGIfont
  1536.  
  1537.  
  1538. RegisterBGIfont function
  1539. ----------------------------------------------------------------
  1540. Declaration: 
  1541.      function RegisterBGIfont (Font: Pointer) : Integer;
  1542.  
  1543. Example:
  1544.      See the "Linking Driver and Font Files" section of Chapter 5, "Turbo
  1545. Pascal Graphics" in the Borland Pascal Developer's Guide.
  1546.  
  1547. Purpose:
  1548.      When font (.CHR) files are linked into the .EXE executable program file,
  1549. you must register the font's location with the Graph unit.  RegisterBGIfont
  1550. takes a pointer to the entry point routine for the driver file.  This entry
  1551. point name comes from the public symbol name name that you assigned when
  1552. converting the .CHR file to a .OBJ file using BINOBJ.
  1553.      RegisterBGIfont returns a negative value to indicate that an error has
  1554. occurred, and a positive or zero value indicates success and is the internal
  1555. font number.
  1556.      RegisterBGIfont is also used in conjunction with loading a disk-based font
  1557. file into a memory buffer to improve display performance when you need to
  1558. frequently switch back and forth between stroked fonts.  Normally, the Graph
  1559. unit loads one stroked font at a time.  Each time that you switch to a new
  1560. font, the new font must be read (or reread) into memory.  By adding code like
  1561. the following, prior to calling InitGraph, you can read one or more fonts into
  1562. buffers that your program manages separately from the Graph unit:
  1563.  
  1564.      var
  1565.        FontFile : File;
  1566.        PFontBuffer : Pointer;
  1567.      ...
  1568.      Assign ( FontFile, '\TP\BGI\GOTH.CHR' );
  1569.      {$I-}
  1570.      Reset ( FontFile );
  1571.      { Check IOResult here }
  1572.  
  1573.      {Allocate a buffer big enough to hold the entire font file}
  1574.      GetMem ( PFontBuffer, FileSize ( FontFile ) );
  1575.      BlockRead ( FontFile, PFontBuffer, FileSize ( FontFile ));
  1576.      FontID := RegisterBGIfont ( PFontBuffer );
  1577.  
  1578. This code reads the Gothic font into a memory buffer separate from the standard
  1579. font buffer.  As a result, when you select a font using SetTextStyle, you can
  1580. switch between one other stroked font and the Gothic font.  Once the Gothic
  1581. font is registered, the Graph unit knows to look at your memory buffer rather
  1582. than read the font from disk.
  1583.      Note that fonts which have been linked to the .EXE file are already stored
  1584. in memory and are not read in at each call to SetTextStyle.
  1585. See "Linking Driver and Font Files", InitGraph, RegisterBGIfont
  1586.  
  1587.  
  1588. RestoreCrtMode procedure
  1589. ----------------------------------------------------------------
  1590. Declaration: 
  1591.      procedure RestoreCrtMode;
  1592.  
  1593. Example:
  1594.      See GetGraphMode for an example.
  1595.  
  1596. Purpose:
  1597.      While in graphics mode (after calling InitGraph), call RestoreCrtMode to
  1598. switch from the graphics mode back to text mode operation.  Use SetGraphMode to
  1599. switch from text back to graphics.
  1600. See InitGraph, SetGraphMode
  1601.  
  1602.  
  1603. Sector procedure
  1604. ----------------------------------------------------------------
  1605. Declaration: 
  1606.      procedure Sector( X, Y : Integer; StAngle, EndAngle,
  1607.                         XRadius, YRadius : Word );
  1608.  
  1609. Example:
  1610.      Sector ( GetMaxX div 2, GetMaxY div 2, 0, 90, 100, 100 );
  1611.  
  1612. Purpose:
  1613.      Sector is the underlying graphics drawing routine used by PieSlice,
  1614. FillEllipse and so on.  Sector draws and fills an ellipse centered on (X, Y)
  1615. and having an X axis radius of XRadius and a Y axis radius of YRadius.  StAngle
  1616. and EndAngle delineate a subset of the total ellipse, with 0 degrees at the 3
  1617. O'clock position, 90 degrees at 12 O'clock, 180 degrees at 9 O'clock.   The
  1618. ellipse is filled with the current fill pattern from SetFillStyle or
  1619. SetFillPattern, and bounded in the current color from the last SetColor.
  1620. See Circle, Ellipse, Fillellipse, PieSlice, SetAspectRatio, SetFillStyle,
  1621. SetFillPattern
  1622.  
  1623.  
  1624. SetActivePage procedure
  1625. ----------------------------------------------------------------
  1626. Declaration:
  1627.      procedure SetActivePage ( Page : Word );
  1628.  
  1629. Example:
  1630.    1  { PAGEDEMO.PAS }
  1631.    2  program PageDemo;
  1632.    3  { Demonstrates multiple video pages by writing to page #0
  1633.        and displaying
  1634.    4    that page.  Then, by calling SetActivePage ( 1 ),
  1635.        switches to Page #1
  1636.    5    and sends output to that page while still display page
  1637.        #0.  After
  1638.    6    writing the output to Page #1, the program then switches
  1639.        back and
  1640.    7    forth between the two pages.
  1641.    8    This program should only be run in graphic modes that
  1642.        support
  1643.    9    multiple pages.
  1644.   10  }
  1645.   11  uses
  1646.   12    Graph;
  1647.   13  
  1648.   14  var
  1649.   15    GraphBuffer : Pointer;
  1650.   16    GraphDriver, GraphMode : Integer;
  1651.   17    TheText : String;
  1652.   18  
  1653.   19  begin
  1654.   20    { Check for VGA and select a multi-page mode }
  1655.   21    DetectGraph ( GraphDriver, GraphMode );
  1656.   22  
  1657.   23    { This code may be different for your monitor }
  1658.   24    if  GraphDriver = VGA then
  1659.   25      GraphMode := VGALo;
  1660.   26  
  1661.   27    InitGraph ( GraphDriver, GraphMode, '\BP\BGI');
  1662.   28  
  1663.   29    SetVisualPage ( 0 );
  1664.   30    SetActivePage ( 0 );
  1665.   31  
  1666.   32    SetTextJustify (CenterText, CenterText);
  1667.   33    SetTextStyle( TriplexFont, HorizDir, 3);
  1668.   34    OutTextXY (GetMaxX div 2, GetMaxY div 2, 'This is Page #0');
  1669.   35  
  1670.   36    SetActivePage ( 1 );
  1671.   37    OutTextXY ( GetMaxX div 2, GetMaxY div 2, 'This is Page # 1');
  1672.   38    Line ( 50, 50, 150, 150 );
  1673.   39    Readln;
  1674.   40    SetVisualPage ( 1 );
  1675.   41    Readln;
  1676.   42    SetVisualPage ( 0 );
  1677.   43    Readln;
  1678.   44  
  1679.   45    CloseGraph;
  1680.   46  end.
  1681.  
  1682. Purpose:
  1683.      Use in conjunction with SetVisualPage for directing graphics output to an
  1684. off screen display area.  These functions are especially useful when drawing
  1685. complex scenes.  The time consuming drawing does not appear on screen until a
  1686. SetVisualPage selects the off screen display area and the screen is instantly
  1687. updated with the new drawing.
  1688.  
  1689. Important!
  1690.      Only the following drivers and modes support multiple screen pages:
  1691.  
  1692. Mode Value  Driver   Mode       Resolution    Palette   Pages
  1693.     0       EGA      EGALo      640x200        16 color  4
  1694.     1                EGAHi      640x350        16 color  2
  1695.  
  1696.     3       EGAMono  EGAMonoHi  640x350 [256k card]      2 color               
  1697. 2
  1698.  
  1699.     0       HercMono HerccMonoHi               720x348   2 color               
  1700. 2
  1701.     
  1702.     0       VGA      VGALo      640x200        16 color  2
  1703.     1                VGAMed     640x350        16 color  2
  1704.  
  1705. Do not use SetVisualPage or SetActivePage without first insuring that the
  1706. GraphDriver parameter returned by InitGraph is equal to EGA, EGAMono, HercMono
  1707. or VGA.  Note that some of these drivers also support single page modes (such
  1708. as VGA) so you should also check the current mode, or explicitly select a
  1709. graphics mode before calling InitGraph (see DetectGraph and InitGraph).  The
  1710. EGAMono driver supports multiple pages only for the 256k card, and not for the
  1711. 64k card.
  1712. See DetectGraph, GetGraphMode, InitGraph, SetVisualPage
  1713.  
  1714.  
  1715. SetAllPalette procedure
  1716. ----------------------------------------------------------------
  1717. Declaration:
  1718.     procedure SetAllPalette (var Palette);
  1719.  
  1720. Example:
  1721.     var
  1722.        PaletteRecord : PaletteType;
  1723.     ...
  1724.     GetPalette ( PaletteRecord ); { Get existing color palette }
  1725.     with PaletteRecord do
  1726.     begin
  1727.        Colors[4] := Brown;        { Map entry #4 to Brown }
  1728.        Colors[5] := Blue;         { Map entry #5 to Blue }
  1729.     end;
  1730.     SetAllPalette ( PaletteRecord );               
  1731.           { And make the palette active }
  1732.  
  1733. Purpose:
  1734.     Use SetPalette to change the entire color palette in a single procedure
  1735. call.  Palette is typically a record of type PaletteType (see PaletteType),
  1736. containing a Size byte specifying the length of the palette, and an array of
  1737. ShortInt values, indexed from 0 to 15.  Each value in the array contains one of
  1738. the color values shown in the chart below, or -1, meaning that no change should
  1739. be made to this entry.
  1740.  
  1741. Chart of Color Constants
  1742.  
  1743. Constants      Value
  1744. Black          0
  1745. Blue                              0
  1746. Green          2
  1747. Cyan                              3
  1748. Red            4
  1749. Magenta        5
  1750. Brown          6
  1751. LightGray      7
  1752. DarkGray       8
  1753. LightBlue      9
  1754. LightGreen     10
  1755. LightCyan      11
  1756. LightRed       12
  1757. LightMagenta   13
  1758. Yellow         14
  1759. White          15
  1760.  
  1761.     The default 16 color palette contains the values in the chart, below.  When
  1762. you use SetColor to select a current drawing color, such as SetColor (4), you
  1763. are selecting the 4th entry in the palette, which maps to the color red.  By
  1764. placing a different value in the 4th entry, for instance, Brown, future
  1765. references to the 4th color (SetColor(4)) then select the color brown.
  1766.     SetAllPalette (and SetPalette) are useful for changing the color of
  1767. existing items on the screen, without redrawing the objects in the new color. 
  1768. The easiest way to change the entire palette is to call GetPalette to fetch the
  1769. current color palette.  Then, change the desired entries in the palette and
  1770. call SetAllPalette.  The color changes are made immediately without any
  1771. redrawing actually occurring.  This is because all of the color attributes on
  1772. the screen are mapped through the graphics color palette.  Changing an entry
  1773. causes all objects having that color to instantly change on the screen.
  1774.     By setting all the unchanged entries to -1, you can set just a few entries
  1775. to new color values.   The entries containing -1 are ignored when calling
  1776. SetAllPalette so only the desired palette entries are changed.  If you wish to
  1777. change just a single entry in the Palette to a new color value, consider using
  1778. SetPalette.
  1779.  
  1780. Important!
  1781.     Color palettes are used only for the EGA and VGA graphics drivers (256
  1782. color IBM 8514 used the SetRGBPalette procedure).  The CGA has hardwired color
  1783. palettes that cannot be rearranged (see list of graphics modes at
  1784. GetGraphMode).
  1785. See GetDefaultPalette, GetPalette, PaletteType, SetPalette, SetRGBPalette
  1786.  
  1787.  
  1788. SetAspectRatio procedure
  1789. ----------------------------------------------------------------
  1790. Declaration:
  1791.     procedure SetAspectRatio ( Xasp, Yasp : Word );
  1792.  
  1793. Example:
  1794.    1  { ASPECTR.PAS }
  1795.    2  program AspectRatio;
  1796.    3  { Demonstrates the effect of varying the aspect ratio
  1797.    4    on circle drawing. Increasing Xasp results in an
  1798.    5    increasingly elliptical circle, in the Y axis.
  1799.    6    Decreasing Xasp or increasing Yasp produces a
  1800.    7    increasing ellipse in the horizontal direction.
  1801.    8  }
  1802.    9  uses
  1803.   10    Crt, Graph;
  1804.   11  
  1805.   12  var
  1806.   13    { Parameters to InitGraph }
  1807.   14    GraphDriver : Integer;
  1808.   15    GraphError  : Integer;
  1809.   16    GraphMode   : Integer;
  1810.   17    { X and Y aspect ratio values }
  1811.   18    Xasp, Yasp  : Word;
  1812.   19    { Used for display purposes }
  1813.   20    XString,
  1814.   21    YString     : String[20];
  1815.   22  
  1816.   23  procedure ClearSection ( X1, Y1, X2, Y2 : Integer );
  1817.   24  begin
  1818.   25    SetViewPort (X1, Y1, X2, Y2, ClipOff);
  1819.   26    ClearViewPort;
  1820.   27    SetViewPort (0, 0, GetMaxX, GetMaxY, ClipOn);
  1821.   28  end;
  1822.   29  
  1823.   30  begin
  1824.   31  
  1825.   32    { Request autodetection of correct graphics driver }
  1826.   33    GraphDriver := Detect;
  1827.   34  
  1828.   35    { Initialize graphics system; look for driver files
  1829.   36      in specified directory }
  1830.   37    InitGraph ( GraphDriver, GraphMode, 'F:\BP\BGI' );
  1831.   38  
  1832.   39    GraphError := GraphResult;
  1833.   40    if GraphError <> grOk  then
  1834.   41    begin
  1835.   42      Writeln('Error occurred:', GraphErrorMsg(GraphError));
  1836.   43      Halt(1);
  1837.   44    end;
  1838.   45  
  1839.   46    { Display prompt line }
  1840.   47    SetTextJustify ( LeftText, BottomText );
  1841.   48    SetTextStyle ( DefaultFont, HorizDir, 1 );
  1842.   49    OutTextXY ( 10, GetMaxY - 10, 'Press any key to stop.');
  1843.   50  
  1844.   51    SetTextJustify( LeftText, TopText );
  1845.   52    GetAspectRatio ( Xasp, Yasp );
  1846.   53    repeat
  1847.   54      Yasp := Yasp - 25;
  1848.   55      SetAspectRatio ( Xasp, Yasp );
  1849.   56      Circle ( GetMaxX div 2, GetMaxY div 2, 75 );
  1850.   57      Str( Xasp:5, XString );
  1851.   58      Str( Yasp:5, YString );
  1852.   59      { Clear out a section on the screen and ... }
  1853.   60      ClearSection (10, 10, 10+TextWidth(XString+', '
  1854.   61                     +YString), 10+TextHeight(XString));
  1855.   62      { Display current Xasp and Yasp values }
  1856.   63      OutTextXY ( 10, 10, XString + ', ' + YString );
  1857.   64    until KeyPressed;
  1858.   65  
  1859.   66  
  1860.   67    CloseGraph;
  1861.   68  
  1862.   69  end.
  1863.  
  1864. Purpose:
  1865.     If circles appear more like ellipses on your monitor (a common problem), it
  1866. means that your monitor is slightly out of alignment.  Rather than fixing the
  1867. hardware, its easier to modify the graphics drawing algorithms by calling
  1868. SetAspectRatio and varying the Xasp and Yasp parameters until a true circle
  1869. appears.  See the example code, above, for a routine that you can use to help
  1870. calibrate the software for any monitor.
  1871. See Arc, Circle, GetAspectRatio
  1872.  
  1873. SetBkColor procedure
  1874. ----------------------------------------------------------------
  1875. Declaration:             
  1876.     procedure SetBkColor ( ColorNum : Word );
  1877.  
  1878. Example:
  1879.     { Select palette entry #1 for background color }
  1880.     SetBkColor( 1 );
  1881.  
  1882. Purpose:
  1883.     Use SetBkColor to choose a background color for the screen where ColorNum
  1884. is the palette index containing the color to choose.  In other words, write
  1885. SetBkColor(3) to select the 3d entry in the palette.  SetBkColor(0) always
  1886. choosed black for the background color, regardless of the current value of the
  1887. 0th entry in the palette.
  1888. See SetAllPalette, SetColor, SetPalette
  1889.  
  1890.  
  1891. SetColor procedure
  1892. ----------------------------------------------------------------
  1893. Declaration:
  1894.     procedure SetColor ( Color : Word );
  1895.  
  1896. Example:
  1897.     { Draws line in palette color #3 }
  1898.     SetColor ( 3 );
  1899.     Line( 10, 10, 45, 100 );                       
  1900.  
  1901.     { Draws rectangle in palette color #5 }
  1902.     SetColor ( 5 );
  1903.     Rectangle ( 10, 10, 200, 200 );
  1904.  
  1905. Purpose:
  1906.     Selects the palette entry specified by Color and makes that entry the
  1907. current drawing color (See SetAllPalette).  This color selection remains in
  1908. effect until the next SetColor call, and applies to all line drawing
  1909. procedures, Rectangle, Arc, Circle, the border color for the ellipse routines
  1910. and others.  For solid or filled interior objects, the interior color is
  1911. selected with SetFillStyle or SetFillPattern.
  1912.      Color values range from 0 to 15 (See SetAllPalette for a list of default
  1913. colors) for EGA and VGA screens, 0 to 3 for CGA color palettes (See Graph Unit
  1914. constants for the CGA color modes available), and 0 to 1 for monochrome or 2
  1915. color schemes.  You can obtain the current maximum number of available colors
  1916. by calling GetMaxColor, which returns a number from 1 to 15.
  1917. See GetColor, GetMaxColor, SetAllPalette, SetBkColor, SetFillStyle,
  1918. SetFillPattern, SetPalette, SetRGBPalette
  1919.  
  1920.  
  1921. SetFillPattern procedure
  1922. ----------------------------------------------------------------
  1923. Declaration:
  1924.     procedure SetFillPattern 
  1925.        (Pattern : FillPatternType; Color : Word );
  1926.  
  1927. Example:
  1928.  
  1929.    1  { CUSTOMPA.PAS }
  1930.    2  program CustomPattern;
  1931.    3  
  1932.    4  { Use this program to help you design a custom fill
  1933.    5    pattern. After the 8 x 8 grid displays, you can use
  1934.    6    the arrow keys to navigate to a specific bit, and set
  1935.    7    it to a 1 by pressing the 1 key, or clearing the bit
  1936.    8    by pressing the 0 key. Press the Esc key to terminate
  1937.    9    data entry and a sample filled circle is displayed on
  1938.   10    the screen. Press Enter to return to pattern editing,
  1939.   11    or press Esc key again to terminate the program.
  1940.   12  }
  1941.   13  
  1942.   14  uses
  1943.   15    Crt, Graph;
  1944.   16  
  1945.   17  const
  1946.   18    { Key equates for the extended key strokes,
  1947.   19      plus Key0 and Key1 for 0 and 1}
  1948.   20    UpArrow       = 72 shl 8;
  1949.   21    LeftArrow     = 75 shl 8;
  1950.   22    RightArrow    = 77 shl 8;
  1951.   23    DownArrow     = 80 shl 8;
  1952.   24    EscapeKey     = 27;
  1953.   25    Key0          = 48;
  1954.   26    Key1          = 49;
  1955.   27  
  1956.   28  var
  1957.   29    { Parameters to InitGraph }
  1958.   30    GraphDriver : Integer;
  1959.   31    GraphError  : Integer;
  1960.   32    GraphMode   : Integer;
  1961.   33    { Holds the pattern that we are designing }
  1962.   34    UserPattern : FillPatternType;
  1963.   35    { X, Y position in the matrix }
  1964.   36    X, Y        : Integer;
  1965.   37    { The key that has been pressed }
  1966.   38    KeyCode     : Word;
  1967.   39    F           : File of Byte;
  1968.   40  
  1969.   41  procedure BitPlot (X, Y : Integer; BitValue : Boolean );
  1970.   42  { Displays each bit in the pattern as a 1 or 0,
  1971.   43    on the display }
  1972.   44  begin
  1973.   45    GotoXY ( X*4, Y * 1 );
  1974.   46    If BitValue then
  1975.   47      write('1')
  1976.   48    else
  1977.   49      write('0');
  1978.   50  end;
  1979.   51  
  1980.   52  
  1981.   53  procedure DisplayPattern ( APattern : FillPatternType );
  1982.   54  { Displays the entire pattern on the screen }
  1983.   55  var
  1984.   56    X, Y : Integer;
  1985.   57  begin
  1986.   58    for X := 1 to 8 do
  1987.   59      for Y := 1 to 8 do
  1988.   60      begin
  1989.   61        BitPlot ( X, Y, (APattern[X] and (256 shr Y)) <> 0);
  1990.   62      end;
  1991.   63  end;
  1992.   64  
  1993.   65  
  1994.   66  procedure GetChar ( var Key : Word );
  1995.   67  { Reads a character from the keyboard, placing
  1996.   68    extended bytes into the high byte of the word
  1997.   69    value returned }
  1998.   70  begin
  1999.   71    Key := Word( ReadKey );
  2000.   72    if  Key = 0  then
  2001.   73      { Read extended byte character code }
  2002.   74      Key := Word( ReadKey) shl 8;
  2003.   75  end;
  2004.   76  
  2005.   77  {$I-}
  2006.   78  begin
  2007.   79    Writeln;
  2008.   80    { Set the initial pattern to all 0's (no
  2009.   81      pattern at all) }
  2010.   82    FillChar ( UserPattern, SizeOf ( FillPatternType ), 0 );
  2011.   83  
  2012.   84    Assign( F, 'PATTERN' );
  2013.   85    Reset ( F );
  2014.   86    if IOResult = 0 then
  2015.   87    begin
  2016.   88      Write('Read in existing PATTERN file (Y/N=Cr)? ');
  2017.   89      GetChar ( KeyCode );
  2018.   90      if (KeyCode = Ord('Y')) or
  2019.   91         (KeyCode = Ord('y'))  then
  2020.   92           for X := 1 to 8 do
  2021.   93             Read(F,  UserPattern[X] );
  2022.   94      Close ( F );
  2023.   95    end;
  2024.   96  
  2025.   97  
  2026.   98    { Request autodetection of correct graphics driver }
  2027.   99    GraphDriver := Detect;
  2028.  100  
  2029.  101    { Initialize graphics system; look for driver files
  2030.  102      in specified directory.  You must change the directory
  2031.  103      to the appropriate directory for you system. }
  2032.  104    InitGraph ( GraphDriver, GraphMode, 'F:\BP\BGI' );
  2033.  105  
  2034.  106    GraphError := GraphResult;
  2035.  107    if GraphError <> grOk  then
  2036.  108    begin
  2037.  109      Writeln('Error occurred:', GraphErrorMsg(GraphError) );
  2038.  110      Halt(1);
  2039.  111    end;
  2040.  112  
  2041.  113    { Enter the editing loop }
  2042.  114    repeat
  2043.  115      RestoreCrtMode;
  2044.  116  
  2045.  117      DisplayPattern ( UserPattern );
  2046.  118  
  2047.  119      Gotoxy ( 1, 10 );
  2048.  120      Writeln( 'Use arrow keys to navigate.');
  2049.  121      Writeln(
  2050.  122       'Press 1 to set a bit, press 0 to clear a bit.' );
  2051.  123      Writeln( 'Press Esc key to see the result.' );
  2052.  124      Writeln(
  2053.  125       'Press Esc key TWICE to terminate the program');
  2054.  126      X := 1;
  2055.  127      Y := 1;
  2056.  128      repeat
  2057.  129        GotoXY ( X*4, Y * 1);
  2058.  130        GetChar ( KeyCode );
  2059.  131        case KeyCode of
  2060.  132          Key0:
  2061.  133          begin
  2062.  134            write('0');       { Clear the bit }
  2063.  135            UserPattern[X] :=
  2064.  136              UserPattern[X] and not (256 shr Y);
  2065.  137          end;
  2066.  138          Key1:
  2067.  139          begin
  2068.  140            write('1');       { Set the bit }
  2069.  141            UserPattern[X] :=
  2070.  142              UserPattern[X] or (256 shr Y) ;
  2071.  143          end;
  2072.  144          UpArrow:        if Y > 1 then Dec(Y);
  2073.  145          DownArrow:      if Y < 8 then Inc(Y);
  2074.  146          LeftArrow:      if X > 1 then Dec(X);
  2075.  147          RightArrow:     if X < 8 then Inc(X);
  2076.  148        end;
  2077.  149        Gotoxy ( X*4, Y * 1);
  2078.  150      until KeyCode = EscapeKey;
  2079.  151  
  2080.  152      { After editing the matrix, return to graphics mode
  2081.  153        and display an object containing the pattern. }
  2082.  154      SetGraphMode ( GetGraphMode );
  2083.  155  
  2084.  156      { Display prompt }
  2085.  157      SetTextJustify ( LeftText, BottomText );
  2086.  158      SetTextStyle ( DefaultFont, HorizDir, 1 );
  2087.  159      OutTextXY ( 10, GetMaxY - 10,
  2088.  160        'Press Esc key to stop, any other key to continue editing.');
  2089.  161  
  2090.  162      SetFillPattern ( UserPattern, 3 );
  2091.  163      FillEllipse( GetMaxX div 2, GetMaxY div 2, 75, 75 );
  2092.  164  
  2093.  165      GetChar( KeyCode );
  2094.  166  
  2095.  167    until KeyCode = EscapeKey;
  2096.  168  
  2097.  169    CloseGraph;
  2098.  170    Write('Save pattern to file PATTERN? (Y/N=CR)? ');
  2099.  171    GetChar(KeyCode);
  2100.  172    if (KeyCode = Ord('Y')) or
  2101.  173       (KeyCode = Ord('y'))  then
  2102.  174    begin
  2103.  175      Assign ( F, 'PATTERN' );
  2104.  176      Rewrite( F );
  2105.  177      for X := 1 to 8 do
  2106.  178        Write( F, UserPattern[X] );
  2107.  179      Close ( F );
  2108.  180    end;
  2109.  181  
  2110.  182  end.
  2111.  
  2112. Purpose:
  2113.     Use SetFillPattern to establish a custom-design pattern for filling the
  2114. interior of all filled graphic objects (FillPoly, FloodFill, Bar, Bar3D,
  2115. PieSlice), and to select the color for that pattern (the interior color is set
  2116. here or in SetFillStyle; the boundary color is set by SetColor).  The example
  2117. program provides a custom-design editor that makes it easy to design your own
  2118. patterns (its also a lot of fun to invent lots of new designs!)
  2119. See SetFillStyle
  2120.  
  2121.  
  2122. SetFillStyle procedure
  2123. ----------------------------------------------------------------
  2124. Declaration:
  2125.     procedure SetFillStyle ( Pattern : Word; Color : Word );
  2126.  
  2127. Example:
  2128.     SetFillStyle ( LtSlashFill, 3 );
  2129.     PieSlice ( GetMaxX div 2, GetMaxY div 2, 0, 90, 100 );
  2130.  
  2131. Purpose:
  2132.     Use SetFillStyle to select one of the standard interior patterns for filled
  2133. objects.  The patterns are selected using one of the constants from Table 7-. 
  2134. You can create custom fill patterns using the SetFillPattern procedure (See
  2135. SetFillPattern for a program to edit new pattern designs).  When the selected
  2136. pattern is UserFill, SetFillStyle lets you select the previously registered
  2137. custom fill pattern.  This way you can flip back and forth between a standard
  2138. fill pattern and a custom fill pattern without having to rebuild the user
  2139. defined  pattern each time.
  2140.  
  2141. The following table shows the available pattern constants and a textual
  2142. description of the pattern that they select:
  2143.  
  2144. Constant   Description
  2145. EmptyFill  
  2146.                Uses the background color for a solid fill.
  2147. SolidFill  
  2148.                Uses the specified color as a solid fill.
  2149. LineFill   
  2150.                Outputs horizontal lines across the object.
  2151. LtSlashFill             
  2152.                Outputs slanted lines (to the right) across the object.
  2153. SlashFill  
  2154.                Outputs thick slanted lines (to the right) across the object.
  2155. BkSlashFill             
  2156.                Outputs thick slanted lines (to the left) across the object.
  2157. LtBkSlashFill
  2158.                Outputs slanted lines (to the left)across the object.
  2159. HatchFill  
  2160.                Displays a "cross hatch" pattern.
  2161. XHatchFill 
  2162.                Displays a thicker "cross hatch" pattern.
  2163. InterleaveFill
  2164.                Outputs a tightly spaced line fill.
  2165. WideDotFill             
  2166.                Outputs a dot fill pattern with the dots widely                 
  2167.                spaced.
  2168. CloseDotFill            
  2169.                Closely spaced dot fill pattern.
  2170. UserFill   
  2171.                Selects the user defined fill pattern.
  2172.  
  2173. See SetUserPattern
  2174.  
  2175.  
  2176. SetGraphBufSize procedure
  2177. ----------------------------------------------------------------
  2178. Declaration:  
  2179.     procedure SetGraphBufSize ( BufSize : Word );
  2180. Example:
  2181.     { Adjust buffer size BEFORE InitGraph }
  2182.     SetGraphBufSize ( 8192 );     
  2183.     GraphDriver := Detect;
  2184.     InitGraph ( GraphDriver, GraphMode, '' );
  2185.  
  2186. Purpose:
  2187.     The internal algorithm used to fill an area on the screen using
  2188. FillEllipse, Sector, PieSlice, FloodFill, and so on, requires the use of a
  2189. memory buffer.  By default this buffer is set to 4,096 bytes, which is
  2190. sufficient for fairly complicated polygon shapes (up to approximately 650
  2191. vertices).  However, in the event that one of the filled object drawing
  2192. procedures sets GraphResult to grNoScanMem or grNoFloodMem you should set the
  2193. buffer area to a larger size by calling SetGraphBufSize and setting BufSize to
  2194. the new size, in bytes.  The call to SetGraphBufSize must be made before
  2195. calling InitGraph.
  2196. See GraphResult
  2197.  
  2198.  
  2199. SetGraphMode procedure
  2200. ----------------------------------------------------------------
  2201. Declaration:  
  2202.     procedure SetGraphMode ( Mode : Integer );
  2203.  
  2204. Example:
  2205.     InitGraph ( GraphDriver, GraphMode, '' );
  2206.     ...
  2207.     { Switch back to text mode for a bit }
  2208.     RestoreCrtMode;          
  2209.     Write('Verify correct display (Y/N)? ');
  2210.     Readln( Answer );
  2211.     ...
  2212.     { Switch back to graphics mode }
  2213.     SetGraphMode( GetGraphMode ); 
  2214.  
  2215. Purpose:
  2216.      SetGraphMode is used to select a different graphics mode for the current
  2217. driver (such as switching between VGAHi, VGAMed, or VGALo after the graphics
  2218. program is executing).  As such, you must only call SetGraphMode after first
  2219. calling InitGraph.  During program execution you can switch back and forth
  2220. between text and graphics modes by calling RestoreCrtMode to switch to text
  2221. mode, and then calling SetGraphMode(GetGraphMode) to switch back to the
  2222. previous graphics mode.
  2223.     See GetGraphMode for a complete list of available modes per driver.
  2224. See DetectGraph, GetGraphMode, GetModeRange, GraphResult, InitGraph,
  2225. RestoreCrtMode
  2226.  
  2227.  
  2228. SetPalette procedure
  2229. ----------------------------------------------------------------
  2230. Declaration:
  2231.     procedure SetPalette ( ColorNum : Word; Color : ShortInt );
  2232.  
  2233. Example:
  2234.     { Changes 4th entry to Green color }
  2235.     SetPalette ( 4, Green ); 
  2236.  
  2237. Purpose:
  2238.     SetPalette changes individual entries in the color palette (See
  2239. SetAllPalette for a procedure that can change the entire palette in a single
  2240. call).  ColorNum is a palette index from 0 to 15, although some graphics
  2241. drivers support fewer than 16 entries.  Call GetMaxColor (or GetPaletteSize-1)
  2242. to determine the maximum numbers of colors that are currently available.  See
  2243. SetAllPalette and the section titled "Selecting Interior Color for Objects",
  2244. earlier in this chapter for additional information.
  2245. See GetMaxColor, GetPaletteSize, SetAllPalette, SetBkColor, SetColor,
  2246. SetRGBPalette
  2247.  
  2248.  
  2249. SetRGBPalette procedure
  2250. ----------------------------------------------------------------
  2251. Declaration:  
  2252.     procedure SetRGBPalette
  2253.        (ColorNum, RedValue, GreenValue, BlueValue : Integer );
  2254.  
  2255. Example:
  2256.  
  2257.     SetColor(3);
  2258.     OutTextXY (100, 100, 'Here is some text in color #3');
  2259.  
  2260.     { Change the value of palette entry #3 to every possible
  2261.     color.  This will take a while! }
  2262.     for I1 := 0 to 63 do
  2263.        for I2 := 0 to 63 do
  2264.           for I3 := 0 to 63 do
  2265.             begin
  2266.               SetRGBPalette( 3, I1, I2, I3 );
  2267.               delay(50);
  2268.             end;
  2269.     Readln;
  2270.  
  2271. Purpose:
  2272.     For the IBM 8514 and VGA device drivers, the 16 basic palette entries are
  2273. programmable.  Using SetRGBPalette you can precisely specify the amount of Red,
  2274. Green or Blue color for each index in the palette, using ColorNum as the index
  2275. value.
  2276.     Each of the color values ranges in value from 0 to 63, with 0 being the
  2277. lowest intensity and 63 being the brightest intensity.  By mixing various
  2278. intensity values between the Red, Green and Blue, you can create custom colors,
  2279. up to a maximum of 262,144 different combinations.  For example,
  2280.     SetRGBPalette ( 0, 35, 20, 60 );
  2281. changes the background color (palette entry #0) to whatever color is produced
  2282. by mixing these combinations of Red (35), Green (20) and Blue (60).
  2283.     For the IBM 8514 only, ColorNum may range from 0 to 255.
  2284.  
  2285.  
  2286. SetTextJustify procedure
  2287. ----------------------------------------------------------------
  2288. Declaration:  
  2289.     procedure SetTextJustify( Horiz, Vert : Word );
  2290.  
  2291. Example:
  2292.  
  2293.     { Center about X, Y }
  2294.     SetTextJustify ( CenterText, CenterText ); 
  2295.     OutTextXY ( 200, 100, 'Hello, World!' );
  2296.  
  2297. Purpose:
  2298.     When text is drawn on the screen using OutText or OutTextXY, the graphical
  2299. representation of the text is drawn relative to (X, Y).  Think of the text as
  2300. being like a rectangular region that just happens to be filled with text.  That
  2301. region contains 4 corners,  By using SetTextJustify, any one of those 4 corners
  2302. can be placed at (X, Y).  For example, if you output a text string to (0, 0),
  2303. you want (0, 0) to mark the upper left corner of the text region.  On the other
  2304. hand, if you display the string at the bottom of the screen, (0, GetMaxY), you
  2305. want (X, Y) to mark the lower left corner of the string; if (X, Y) marked the
  2306. upper left corner, the entire string would fall off the edge of the screen's
  2307. bottom (and somebody would have to clean up the mess...)
  2308.     Using SetTextJustify, you can select the position of the output text around
  2309. the (X, Y) coordinate by passing predefined constant values to the Horiz and
  2310. Vert parameters.  These constants are: LeftText, CenterText, RightText,
  2311. BottomText, CenterText and TopText.
  2312. You should use the LeftText, CenterText and RightText constants for the Horiz
  2313. parameter, and the BottomText, CenterText and TopText parameters for the Vert
  2314. parameter.  Each constant positions one axis of the text box, as shown in the
  2315. following illustrations:
  2316. ***FIG5JUA.PCX***
  2317. ***FIG5JUB.PCX***
  2318. The SetTextJustify settings remain in effect until the next call to
  2319. SetTextJustify.
  2320. See OutText, OutTextXY, SetTextStyle
  2321.  
  2322.  
  2323. SetTextStyle procedure
  2324. ----------------------------------------------------------------
  2325. Declaration:  
  2326.     procedure SetTextStyle 
  2327.        ( Font : Word; Direction : Word; CharSize : Word );
  2328.  
  2329. Example:
  2330.     SetTextStyle ( TriplexFont, HorizDir, 3 );
  2331.     SetTextJustify ( LeftText, BottomText );
  2332.     OutTextXY ( GetMaxX div 2, GetMaxY div 2, 'Hello, World!');
  2333.  
  2334. Purpose:
  2335.     Before performing text ouptut with OutText or OutTextXY, you should call
  2336. SetTextStyle to select a character font, display direction (either horizontal
  2337. or vertical) and relative size of the graphical text.  If you do not call
  2338. SetTextStyle, all output appears in the default 8x8 bitmap font and in the
  2339. smallest size available (8 pixels by 8 pixels).  
  2340.     The fonts are stored in a series of .CHR files, in the same directory as
  2341. the .BGI driver files.   If SetTextStyle cannot locate the appropriate .CHR
  2342. file for the font selected, GraphResult will retain an error code.  To insure
  2343. program reliability, you should test the condition of GraphResult whenever you
  2344. select a new font.
  2345.     You select one of the 5 standard fonts by passing one of these constants to
  2346. SetTextStyle:
  2347.     DefaultFont     8x8 bitmapped font
  2348.     TriplexFont     Stroked font
  2349.     SmallFont Stroked font
  2350.     SansSerifFont   Stroked font
  2351.     GothicFont      Stroked font
  2352. The DefaultFont is a simple an 8x8 bitmap font.  As a consequence, as the font
  2353. is scaled upwards in size, it takes on a "chunky" appearance.  Hence, the
  2354. default font is convenient for small text items such as prompts, messages and
  2355. home brew graphical menu systems.  The remaining fonts are stroked fonts,
  2356. meaning that internally they are stored as graphical vectors, rather than as
  2357. bitmaps.  Stroked fonts can be enlarged significantly in size with no
  2358. degradation in appearance.
  2359.     The Direction parameter chooses whether output text is drawn in the
  2360. horizonal direction, like normal text, or if the text will be drawn vertically
  2361. on the screen.  By setting this parameter to HorizDir you select the horizontal
  2362. direction, and using VertDir you select the vertical direction.
  2363.     CharSize sets a scaling factor to be applied to the font.  For instance, a
  2364. CharSize of 1 for the default font produces the smallest 8 x 8 pixel
  2365. characters.  By setting the CharSize to 3, the font is displayed in a 24 x 24
  2366. pixel array (but still with only 8x8 level resolution).  When using graphical
  2367. fonts, you cannot rely on the usual Length ( aString ) function to determine
  2368. the size of a string when it appears on the screen.  Instead, call the
  2369. TextHeight and TextWidth functions to calculate the graphic item's actual pixel
  2370. height and width, respectively.
  2371. See SetTextJustify, SetUserCharSize, TextHeight, TextWidth
  2372.  
  2373.  
  2374. SetUserCharSize procedure
  2375. ----------------------------------------------------------------
  2376. Declaration:  
  2377.     procedure SetUserCharSize 
  2378.        ( MultX, DivX, MultY, DivY : Word );
  2379.  
  2380. Example:
  2381.  
  2382.     TheText := 'First Graphics Program';
  2383.     SetTextJustify (CenterText, CenterText);
  2384.     SetTextStyle( TriplexFont, HorizDir, 3);
  2385.     SetUserCharSize ( 3, 2, 1, 1 );
  2386.     OutTextXY (GetMaxX div 2, GetMaxY div 2, TheText);
  2387.     
  2388. Purpose:
  2389.     In addition to the CharSize scaling factor set with SetTextStyle, you can
  2390. vary the character width and height of the stroked fonts in fine increments by
  2391. calling SetUserCharSize.  The parameters MultX and DivX set a scaling ratio for
  2392. setting character width, and MultY and DivY set a scaling ratio for character
  2393. height.  For example, in the TriplexFont used in the sample program (Listing 7-
  2394. ) at the beginning of this chapter, you can make the characters 1.5 times wider
  2395. than the normal font by writing:
  2396.     SetUserCharSize ( 3, 2, 1, 1, );
  2397. The ratio 3:2 is applied to the character width, so that each character becomes
  2398. 3/2 or 1.5 times wider.   By varying both values, you can produce remarkeably
  2399. fine degrees of adjustment in the shape of the basic character set.   To make
  2400. the characters small and skinny, you can write:
  2401.     SetUserCharSize ( 1, 4, 1, 1);
  2402. This produces a scaling multiplier of 1/4.  While not shown in these examples,
  2403. scaling values apply similarly to the Y axis.  When both value values, MultX,
  2404. DivX or MultY, DivY are set to 1, then no scaling adjustment is made to the
  2405. respective axis.
  2406. See OutText, OutTextXY, SetTextStyle, SetTextJustify
  2407.  
  2408.  
  2409. SetViewPort procedure
  2410. ----------------------------------------------------------------
  2411. Declaration:  
  2412.     procedure SetViewPort 
  2413.        (X1, Y1, X2, Y2 : Integer; Clip : Boolean);
  2414.  
  2415. Purpose:
  2416.     By default, drawing coordinates are relative to the screen's coordinates,
  2417. with (0, 0) at the upper left corner and (GetMaxX, GetMaxY) at the lower right
  2418. corner.  (Actually, the default viewport is set to (0, 0) to (GetMaxX,
  2419. GetMaxY).   However, using SetViewPort, a new viewing area may be defined as a
  2420. subset of the existing screen.  Subsequent drawing commands arel then drawn
  2421. relative to the location of the viewport region.  For example, to set a
  2422. viewport covering the lower right quadrant of the screen, write:
  2423.     SetViewPort ( GetMaxX div 2, GetMaxY div 2, GetMaxX, GetMaxY, ClipOn );
  2424. This creates a viewport whose upper left corner as at the screen's midpoint and
  2425. whose lower right corner as the screen's lower right corner.
  2426. ***FIG5VIE***
  2427.     Subsequent drawing coordinates are all relative to this viewport
  2428. definition.  As a result, the statement,
  2429.     Line (0, 0, 50, 50 );
  2430. draws a diagonal line from the screen's mid point towards the lower right
  2431. corner of the screen.  This because the coordinates are now relative to the
  2432. viewport.
  2433.     The last parameter to SetViewPort,  Clip, determines what to do about lines
  2434. and other objects that extend beyond the boundaries of the viewport.  When Clip
  2435. is False, no action takes place.  If, using the above viewport, you draw a line
  2436. with a negative X value, like this,
  2437.     Line (-30, 0, 50, 50 );
  2438. the line appears on the screen, extending to the left, as needed.  However,
  2439. when Clip is set to True, the line is truncated at the viewport boundary so
  2440. that the only portion of the line that is visible is that which falls inside
  2441. the viewport.  Two predefined constants ClipOn=True and ClipOff=False make for
  2442. easy readability of the setting of the Clip parameter on calls to SetViewPort. 
  2443. Clipping affects all of the drawing commands, including the filled or solid
  2444. object drawing procedures.
  2445.     When a viewport is in effect, as shown above, you can pass negative
  2446. coordinate values to the drawing commands.  This may be useful to your
  2447. application, particularly if the graphics model you are producing assumes that
  2448. (0, 0) should be positioned in the center of the screen (as is done in basic
  2449. analytic geometry problems).  However, there's not much one can do about the
  2450. coordinate system being upside down (negative Y values are above the 0 X axis,
  2451. rather than below) other than to invert the value of Y before passing to a
  2452. drawing procedure. 
  2453. See ClearViewPort, GetViewPort, ViewPortType
  2454.  
  2455.  
  2456. SetVisualPage procedure
  2457. ----------------------------------------------------------------
  2458. Declaration:  
  2459.     procedure SetVisualPage ( Page : Word );
  2460.  
  2461. Purpose:
  2462.     Used in conjunction with SetActivePage, SetVisualPage enables you to draw
  2463. images "off screen" in separate video memory pages (for those adaptors and
  2464. modes that support multiple video pages).  See SetActivePage for complete
  2465. details on using both SetVisualPage and SetActivePage to implement off screen
  2466. drawing, which is useful for creating animated sequences.
  2467. See SetActivePage
  2468.  
  2469.  
  2470. SetWriteMode procedure
  2471. ----------------------------------------------------------------
  2472. Declaration:  
  2473.     procedure SetWriteMode (WriteMode : Integer);
  2474.  
  2475. Example:
  2476.  
  2477.     SetWriteMode ( XORPut );
  2478.     { Draw the rectangle on the screen }
  2479.     Rectangle ( X, Y, X + Width, Y + Height );
  2480.     Delay ( 1000 );
  2481.     { Still in XOR mode, the second drawing erases the first ! }
  2482.     Rectangle ( X, Y, X + Width, Y + Height );
  2483.  
  2484. Purpose:
  2485.     Several of the drawing commands can be written directly to the screen in a
  2486. destructive form, erasing any previously set pixels, or they can exclusive-or
  2487. the pixels on to the screen.  In the latter case, an item that has been written
  2488. with the exclusive-or (XOR) method, can be erased by writing it again.  This is
  2489. a key method used to move some objects around the screen.
  2490.     The drawing mode is selected by calling SetWriteMode, with the WriteMode
  2491. parameter set to the the constant CopyPut, for a destructive copy to the
  2492. screen, or XORPut for an exclusive-or'ing of pixels on the screen.  
  2493.     Officially, SetWriteMode only affects DrawPoly, Line, LineRel, LineTo and
  2494. Rectangle.  But in actual use I find that SetWriteMode affects some of the
  2495. other drawing commands (PieSlice, OutTextXY), and not always in the way that
  2496. you might like.  As a result, I recommend explicitly selecting
  2497. SetWriteMode(CopyPut) for all drawing commands other than those appearing in
  2498. the list above.
  2499. See Line, LineRel, LineTo, PutImage
  2500.  
  2501.  
  2502. TextHeight function
  2503. ----------------------------------------------------------------
  2504. Declaration:  
  2505.     function TextHeight( TextString : String );
  2506. Example:
  2507.  
  2508.     TheText := 'First Graphics Program';
  2509.     SetTextJustify (CenterText, CenterText);
  2510.     SetTextStyle( TriplexFont, HorizDir, 3);
  2511.     OutTextXY (GetMaxX div 2, GetMaxY div 2, TheText);
  2512.  
  2513.     { Underline the text we've put on the screen }
  2514.     Line ( GetMaxX div 2 - TextWidth (TheText) div 2,
  2515.           GetMaxY div 2 + TextHeight (TheText),
  2516.           GetMaxX div 2 + TextWidth (TheText) div 2,
  2517.           GetMaxY div 2 + TextHeight (TheText) );
  2518.  
  2519. Purpose:
  2520.     Use TextHeight, together with TextWidth, to calculate the height and width
  2521. of graphic text items.  TextHeight computes the height, in pixels, of the
  2522. graphic representation of a string and is useful for determing line spacing or
  2523. distance from another graphic element.  These routines make their computation
  2524. based on the current font and character size.
  2525. See TextWidth
  2526.  
  2527.  
  2528. TextSettingsType type
  2529. ----------------------------------------------------------------
  2530. Declaration:
  2531.  
  2532.     TextSettingsType = record
  2533.        Font : Word;
  2534.        Direction : Word;
  2535.        CharSize : Word;
  2536.        Horiz : Word;
  2537.        Vert : Word;
  2538.     end;
  2539.  
  2540. See SetTextJustify, SetTextStyle
  2541.  
  2542.  
  2543. TextWidth function
  2544. ----------------------------------------------------------------
  2545. Declaration:  
  2546.     function TextWidth ( TextString : String );
  2547.  
  2548. Example:
  2549.     TheText := 'First Graphics Program';
  2550.     SetTextJustify (CenterText, CenterText);
  2551.     SetTextStyle( TriplexFont, HorizDir, 3);
  2552.     OutTextXY (GetMaxX div 2, GetMaxY div 2, TheText);
  2553.  
  2554.     { Underline the text we've put on the screen }
  2555.     Line ( GetMaxX div 2 - TextWidth (TheText) div 2,
  2556.           GetMaxY div 2 + TextHeight (TheText),
  2557.           GetMaxX div 2 + TextWidth (TheText) div 2,
  2558.           GetMaxY div 2 + TextHeight (TheText) );
  2559.  
  2560. Purpose:
  2561.     Use TextWidth, together with TextHeight, to calculate the width and height
  2562. of graphic text items.  TextWidth computes the width, in pixels, of the graphic
  2563. representation of a string and is useful for determining the on-screen length
  2564. of a text line.  These routines make their computation based on the current
  2565. font and character size.
  2566. See TextHeight
  2567.  
  2568.  
  2569. ViewPortType
  2570. ----------------------------------------------------------------
  2571. Declaration:
  2572.  
  2573.     ViewPortType = record
  2574.        X1, Y1, X2, Y2 : Integer;
  2575.        Clip : Boolean;
  2576.     end;
  2577.  
  2578. See SetViewPort, GetViewSettings
  2579.